Getting Started

Kuzzle can be customized and extended using plugins.

This chapter explains how to install and configure a plugin. The other chapters in this section cover the four plugin interfaces exposed by Kuzzle:

A single plugin can implement as many of those interfaces as necessary.

Plugin Boilerplate

The best way to start developing a plugin is to use a boilerplate.

We provide a boilerplate that contain a Kuzzle stack that reloads itself whenever a plugin change is detected, making it a handy tool for plugin development.

Clone this repository to start developing a Kuzzle plugin:

git clone
cd kuzzle-core-plugin-boilerplate
docker-compose -f docker/docker-compose.yml up
// Kuzzle stack with the plugin is ready
// Edit the file lib/index.js, 
// the Kuzzle stack will automaticaly restart to include your modifications



Plugins are subdirectories that must be put at the following location: <kuzzle_install_dir>/plugins/enabled.

The recommended way to install a plugin is to put it in plugins/available, and then link it to the plugins/enabled directory.

Node.js modules

Kuzzle loads plugins as Node.js modules.

This means that a plugin directory must contain either:

  • an index.js file


  • a valid package.json file. If the plugin's entrypoint is not the root index.js file, then the main property must be filled


Kuzzle needs a few information to make your plugin work properly. These information must be provided in a manifest.json file, in the plugin directory.

The following properties can be defined in this manifest.json file:

  • name (required): plugin unique identifier. Names can only contain lowercase letters, numbers, hyphens and underscores.
  • kuzzleVersion: a non-empty string describing a semver range, limiting the range of Kuzzle versions supported by this plugin. If not set, a warning is displayed on the console, and Kuzzle assumes that the plugin is only compatible with Kuzzle v1.x

Deprecated since v1.5.0

Kuzzle still allows plugins to be loaded without a manifest.json file, for backward compatibility reasons, falling back to the package.json file to retrieve the plugin's name. This will change in next major releases of Kuzzle.

init function

Plugins must expose an init function. If it is missing, Kuzzle fails to load the plugin and aborts its start sequence.

The init method is called once during startup, and it is used to initialize the plugin.


init (config, context)

Arguments Type Description
Contains the custom plugin configuration (see the configuration chapter)
The plugin context, exposing various accessors, constructors, and helpers. The other sections of this documentation detail the interfaces made available by this object


The init function can optionally return a promise. If it does, Kuzzle waits for the promise to be resolved before continuing its own initialization.

If a promise is returned, it must be resolved within the configured timeout (see plugins.common.initTimeout in Kuzzle's configuration)

If a promise is returned and rejected, or if the init function throws an error, Kuzzle aborts its start sequence and shuts down.


When Kuzzle calls the plugin init method, it passes the plugin's custom configuration to it.

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

For example:

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