Skip to content

Application API

createApp()

Creates an application instance.

  • Type

    function createApp(rootComponent: Component, rootProps?: object): App
    
  • Details

    The first argument is the root component. The second optional argument is the props to be passed to the root component.

  • Example

    With inline root component:

    import { createApp } from 'kdu'
    
    const app = createApp({
      /* root component options */
    })
    

    With imported component:

    import { createApp } from 'kdu'
    import App from './App.kdu'
    
    const app = createApp(App)
    
  • See also: Guide - Creating a Kdu Application

createSSRApp()

Creates an application instance in SSR Hydration mode. Usage is exactly the same as createApp().

app.mount()

Mounts the application instance in a container element.

  • Type

    interface App {
      mount(rootContainer: Element | string): ComponentPublicInstance
    }
    
  • Details

    The argument can either be an actual DOM element or a CSS selector (the first matched element will be used). Returns the root component instance.

    If the component has a template or a render function defined, it will replace any existing DOM nodes inside the container. Otherwise, if the runtime compiler is available, the innerHTML of the container will be used as the template.

    In SSR hydration mode, it will hydrate the existing DOM nodes inside the container. If there are mismatches, the existing DOM nodes will be morphed to match the expected output.

    For each app instance, mount() can only be called once.

  • Example

    import { createApp } from 'kdu'
    const app = createApp(/* ... */)
    
    app.mount('#app')
    

    Can also mount to an actual DOM element:

    app.mount(document.body.firstChild)
    

app.unmount()

Unmounts a mounted application instance, triggering the unmount lifecycle hooks for all components in the application's component tree.

  • Type

    interface App {
      unmount(): void
    }
    

app.provide()

Provide a value that can be injected in all descendent components within the application.

  • Type

    interface App {
      provide<T>(key: InjectionKey<T> | symbol | string, value: T): this
    }
    
  • Details

    Expects the injection key as the first argument, and the provided value as the second. Returns the application instance itself.

  • Example

    import { createApp } from 'kdu'
    
    const app = createApp(/* ... */)
    
    app.provide('message', 'hello')
    

    Inside a component in the application:

    import { inject } from 'kdu'
    
    export default {
      setup() {
        console.log(inject('message')) // 'hello'
      }
    }
    
    export default {
      inject: ['message'],
      created() {
        console.log(this.message) // 'hello'
      }
    }
    
  • See also:

app.component()

Registers a global component if passing both a name string and a component definition, or retrieves an already registered one if only the name is passed.

  • Type

    interface App {
      component(name: string): Component | undefined
      component(name: string, component: Component): this
    }
    
  • Example

    import { createApp } from 'kdu'
    
    const app = createApp({})
    
    // register an options object
    app.component('my-component', {
      /* ... */
    })
    
    // retrieve a registered component
    const MyComponent = app.component('my-component')
    
  • See also: Component Registration

app.directive()

Registers a global custom directive if passing both a name string and a directive definition, or retrieves an already registered one if only the name is passed.

  • Type

    interface App {
      directive(name: string): Directive | undefined
      directive(name: string, directive: Directive): this
    }
    
  • Example

    import { createApp } from 'kdu'
    
    const app = createApp({
      /* ... */
    })
    
    // register (object directive)
    app.directive('my-directive', {
      /* custom directive hooks */
    })
    
    // register (function directive shorthand)
    app.directive('my-directive', () => {
      /* ... */
    })
    
    // retrieve a registered directive
    const myDirective = app.directive('my-directive')
    
  • See also: Custom Directives

app.use()

Installs a plugin.

  • Type

    interface App {
      use(plugin: Plugin, ...options: any[]): this
    }
    
  • Details

    Expects the plugin as the first argument, and optional plugin options as the second argument.

    The plugin can either be an object with an install() method, or just a function that will be used as the install() method. The options (second argument of app.use()) will be passed along to the plugin's install() method.

    When app.use() is called on the same plugin multiple times, the plugin will be installed only once.

  • Example

    import { createApp } from 'kdu'
    import MyPlugin from './plugins/MyPlugin'
    
    const app = createApp({
      /* ... */
    })
    
    app.use(MyPlugin)
    
  • See also: Plugins

app.mixin()

Applies a global mixin (scoped to the application). A global mixin applies its included options to every component instance in the application.

Not Recommended

Mixins are supported in Kdu 3 mainly for backwards compatibility, due to their widespread use in ecosystem libraries. Use of mixins, especially global mixins, should be avoided in application code.

For logic reuse, prefer Composables instead.

  • Type

    interface App {
      mixin(mixin: ComponentOptions): this
    }
    

app.version

Provides the version of Kdu that the application was created with. This is useful inside plugins, where you might need conditional logic based on different Kdu versions.

  • Type

    interface App {
      version: string
    }
    
  • Example

    Performing a version check inside a plugin:

    export default {
      install(app) {
        const version = Number(app.version.split('.')[0])
        if (version < 3) {
          console.warn('This plugin requires Kdu 3')
        }
      }
    }
    
  • See also: Global API - version

app.config

Every application instance exposes a config object that contains the configuration settings for that application. You can modify its properties (documented below) before mounting your application.

import { createApp } from 'kdu'

const app = createApp(/* ... */)

console.log(app.config)

app.config.errorHandler

Assign a global handler for uncaught errors propagating from within the application.

  • Type

    interface AppConfig {
      errorHandler?: (
        err: unknown,
        instance: ComponentPublicInstance | null,
        // `info` is a Kdu-specific error info,
        // e.g. which lifecycle hook the error was thrown in
        info: string
      ) => void
    }
    
  • Details

    The error handler receives three arguments: the error, the component instance that triggered the error, and an information string specifying the error source type.

    It can capture errors from the following sources:

    • Component renders
    • Event handlers
    • Lifecycle hooks
    • setup() function
    • Watchers
    • Custom directive hooks
    • Transition hooks
  • Example

    app.config.errorHandler = (err, instance, info) => {
      // handle error, e.g. report to a service
    }
    

app.config.warnHandler

Assign a custom handler for runtime warnings from Kdu.

  • Type

    interface AppConfig {
      warnHandler?: (
        msg: string,
        instance: ComponentPublicInstance | null,
        trace: string
      ) => void
    }
    
  • Details

    The warning handler receives the warning message as the first argument, the source component instance as the second argument, and a component trace string as the third.

    It can be used to filter out specific warnings to reduce console verbosity. All Kdu warnings should be addressed during development, so this is only recommended during debug sessions to focus on specific warnings among many, and should be removed once the debugging is done.

    TIP

    Warnings only work during development, so this config is ignored in production mode.

  • Example

    app.config.warnHandler = (msg, instance, trace) => {
      // `trace` is the component hierarchy trace
    }
    

app.config.performance

Set this to true to enable component init, compile, render and patch performance tracing in the browser devtool performance/timeline panel. Only works in development mode and in browsers that support the performance.mark API.

app.config.compilerOptions

Configure runtime compiler options. Values set on this object will be passed to the in-browser template compiler and affect every component in the configured app. Note you can also override these options on a per-component basis using the compilerOptions option.

Important

This config option is only respected when using the full build (i.e. the standalone kdu.js that can compile templates in the browser). If you are using the runtime-only build with a build setup, compiler options must be passed to @kdujs/compiler-dom via build tool configurations instead.

app.config.compilerOptions.isCustomElement

Specifies a check method to recognize native custom elements.

  • Type: (tag: string) => boolean

  • Details

    Should return true if the tag should be treated as a native custom element. For a matched tag, Kdu will render it as a native element instead of attempting to resolve it as a Kdu component.

    Native HTML and SVG tags don't need to be matched in this function - Kdu's parser recognizes them automatically.

  • Example

    // treat all tags starting with 'ion-' as custom elements
    app.config.compilerOptions.isCustomElement = (tag) => {
      return tag.startsWith('ion-')
    }
    
  • See also: Kdu and Web Components

app.config.compilerOptions.whitespace

Adjusts template whitespace handling behavior.

  • Type: 'condense' | 'preserve'

  • Default: 'condense'

  • Details

    Kdu removes / condenses whitespace characters in templates to produce more efficient compiled output. The default strategy is "condense", with the following behavior:

    1. Leading / ending whitespace characters inside an element are condensed into a single space.
    2. Whitespace characters between elements that contain newlines are removed.
    3. Consecutive whitespace characters in text nodes are condensed into a single space.

    Setting this option to 'preserve' will disable (2) and (3).

  • Example

    app.config.compilerOptions.whitespace = 'preserve'
    

app.config.compilerOptions.delimiters

Adjusts the delimiters used for text interpolation within the template.

  • Type: [string, string]

  • Default: ['{{', '}}']

  • Details

    This is typically used to avoid conflicting with server-side frameworks that also use mustache syntax.

  • Example

    // Delimiters changed to ES6 template string style
    app.config.compilerOptions.delimiters = ['${', '}']
    

app.config.compilerOptions.comments

Adjusts treatment of HTML comments in templates.

  • Type: boolean

  • Default: false

  • Details

    By default, Kdu will remove the comments in production. Setting this option to true will force Kdu to preserve comments even in production. Comments are always preserved during development. This option is typically used when Kdu is used with other libraries that rely on HTML comments.

  • Example

    app.config.compilerOptions.comments = true
    

app.config.globalProperties

An object that can be used to register global properties that can be accessed on any component instance inside the application.

  • Type

    interface AppConfig {
      globalProperties: Record<string, any>
    }
    
  • Details

    This is a replacement of Kdu 2's Kdu.prototype which is no longer present in Kdu 3. As with anything global, this should be used sparingly.

    If a global property conflicts with a component’s own property, the component's own property will have higher priority.

  • Usage

    app.config.globalProperties.msg = 'hello'
    

    This makes msg available inside any component template in the application, and also on this of any component instance:

    export default {
      mounted() {
        console.log(this.msg) // 'hello'
      }
    }
    

app.config.optionMergeStrategies

An object for defining merging strategies for custom component options.

  • Type

    interface AppConfig {
      optionMergeStrategies: Record<string, OptionMergeFunction>
    }
    
    type OptionMergeFunction = (to: unknown, from: unknown) => any
    
  • Details

    Some plugins / libraries add support for custom component options (by injecting global mixins). These options may require special merging logic when the same option needs to be "merged" from multiple sources (e.g. mixins or component inheritance).

    A merge strategy function can be registered for a custom option by assigning it on the app.config.optionMergeStrategies object using the option's name as the key.

    The merge strategy function receives the value of that option defined on the parent and child instances as the first and second arguments, respectively.

  • Example

    const app = createApp({
      // option from self
      msg: 'Kdu',
      // option from a mixin
      mixins: [
        {
          msg: 'Hello '
        }
      ],
      mounted() {
        // merged options exposed on this.$options
        console.log(this.$options.msg)
      }
    })
    
    // define a custom merge strategy for `msg`
    app.config.optionMergeStrategies.msg = (parent, child) => {
      return (parent || '') + (child || '')
    }
    
    app.mount('#app')
    // logs 'Hello Kdu'
    
  • See also: Component Instance - $options

Application API has loaded