Plugins creation prerequisites


Writing plugin code

Plugins must be valid NodeJS require-able modules, usually shipped as a directory containing either:

  • an index.js file in its root directory, exporting a valid Javascript class exposing an init method, or
  • a well-formed package.json file in its root directory, specifying the path of the main require-able in the main field.

To determine the Plugin name, Kuzzle looks for the name field in the package.json file falling back to the plugin directory name otherwise.


Custom Plugin configuration

When initializing a Plugin, Kuzzle calls its init(customConfig, context) method, passing the context and the plugin's custom configuration.

Custom configuration parameters are specified for each plugin in the plugins object of the Kuzzle configuration file.

{
  "plugins": {
    "kuzzle-plugin-foobar": {
      "option_1": "option_value",
      "option_2": "option_value"
    }
  }
}

Each Plugin is responsible of handling the custom configuration parameters and Kuzzle has no opinion on how to do it. Whether the custom configuration is merged with the defaults or not entirely depends on the implementation of the init function.

Within a plugin's custom configuration, there are a few reserved words used by Kuzzle to configure how a plugin is loaded:

{
  "plugins": {
    "kuzzle-plugin-foobar": {
      "killTimeout": 6000,
      "maxMemoryRestart": "200M",
      "threads": 0
    }
  }
}

Where:

KeywordTypeDefault ValueDescription
killTimeoutunsigned integer6000(if threads > 0) Time (in milliseconds) to wait for a plugin to shut down before killing it
maxMemoryRestartstring1G(if threads > 0) Maximum memory usage of a worker plugin. If exceeded, the plugin is restarted.
Examples: 10K (10KB), 200M (200MB), 3G (3GB)

Plugin init function

Plugins must expose a init function. If it's missing, Kuzzle will refuse to start.
This method is called by Kuzzle during startup, and should be used to initialize the plugin:

init (config, context) { /* ... */ }

Where:

  • config (JSON Object): JSON object containing the custom plugin configuration
  • context (JSON Object): the plugin context

The init function may:

  • throw an error: Kuzzle will properly shutdown if it does so
  • return a Promise, if async tasks need to be performed. If so, please note that if plugins does not resolve (or reject) the returned Promise within the configured plugins.common.initTimeout parameter (see Configuring Kuzzle), then Kuzzle will shut itself down with a timeout error