Plugins #

Introduction #

Plugins are self-contained code that usually add app-level functionality to Kdu. This is how we install a plugin:

import { createApp } from 'kfu'

const app = createApp({})

app.use(myPlugin, {
  /* optional options */
})

A plugin is defined as either an object that exposes an install() method, or simply a function that acts as the install function itself. The install function receives the app instance along with additional options passed to app.use(), if any:

const myPlugin = {
  install(app, options) {
    // configure the app
  }
}

There is no strictly defined scope for a plugin, but common scenarios where plugins are useful include:

1. Register one or more global components or custom directives with app.component() and app.directive().

2. Make a resource injectable throughout the app by calling app.provide().

3. Add some global instance properties or methods by attaching them to app.config.globalProperties.

4. A library that needs to perform some combination of the above (e.g. kdu-router).

Writing a Plugin #

In order to better understand how to create your own Kdu.js plugins, we will create a very simplified version of a plugin that displays i18n (short for Internationalization) strings.

Let's begin by setting up the plugin object. It is recommended to create it in a separate file and export it, as shown below to keep the logic contained and separate.

// plugins/i18n.js
export default {
  install: (app, options) => {
    // Plugin code goes here
  }
}

We want to make a function to translate keys available to the whole application, so we will expose it using app.config.globalProperties. This function will receive a dot-delimited key string, which we will use to look up the translated string in the user-provided options.

// plugins/i18n.js
export default {
  install: (app, options) => {
    // inject a globally available $translate() method
    app.config.globalProperties.$translate = (key) => {
      // retrieve a nested property in `options`
      // using `key` as the path
      return key.split('.').reduce((o, i) => {
        if (o) return o[i]
      }, options)
    }
  }
}

The plugin expects users to pass in an object containing the translated keys via the options when they use the plugin, so it should be used like this:

import i18nPlugin from './plugins/i18n'

app.use(i18nPlugin, {
  greetings: {
    hello: 'Bonjour!'
  }
})

Our $translate function will take a string such as greetings.hello, look inside the user provided configuration and return the translated value - in this case, Bonjour!:

<h1>{{ $translate('greetings.hello') }}</h1>

See also: Augmenting Global Properties

Provide / Inject with Plugins #

Plugins also allow us to use inject to provide a function or attribute to the plugin's users. For example, we can allow the application to have access to the options parameter to be able to use the translations object.

// plugins/i18n.js
export default {
  install: (app, options) => {
    app.config.globalProperties.$translate = (key) => {
      return key.split('.').reduce((o, i) => {
        if (o) return o[i]
      }, options)
    }

    app.provide('i18n', options)
  }
}

Plugin users will now be able to inject the plugin options into their components using the i18n key:

<script setup>
import { inject } from 'kdu'

const i18n = inject('i18n')

console.log(i18n.greetings.hello)
</script>

export default {
  inject: ['i18n'],
  created() {
    console.log(this.i18n.greetings.hello)
  }
}