Plugin #

Base class for External Plugins.

Plugins registered with the BackendPlugin.use method must extends this abstract class.

Some properties of the Plugin class allows to define a set of features that will be integrated to the plugin.

api #

This property allows to define plugin features.

TypeDescription
PluginApiDefinition
Define new API controllers PluginApiDefinition

The PluginApiDefinition type is an object with each key as a controller name and the value is a valid ControllerDefinition.

type PluginApiDefinition = {
  /**
   * Name of the API controller.
   */
  [controller: string]: ControllerDefinition
}

authenticators #

This property allows to define plugin features.

TypeDescription
JSONObject
Authenticator classes, by name

Each key is an authenticator name, and each value is a class (a constructor) implementing a Passport strategy. The strategies of the plugin refer to them by name, in their config.authenticator property.

Kuzzle throws a plugin.authenticators.not_an_object error if the property is not an object, and a plugin.authenticators.invalid_authenticator error if one of its values is not a constructor.

See also the Integrate an Authentication Strategy guide.

const LocalStrategy = require('passport-local').Strategy;

class MyPlugin extends Plugin {
  constructor () {
    super({ kuzzleVersion: '>=2.8.0 <3' });

    this.authenticators = { Local: LocalStrategy };
  }
}

config #

TypeDescription
JSONObject
Plugin configuration

context #

TypeDescription
PluginContext
PluginContext instance

hooks #

This property allows to define plugin features.

TypeDescription
PluginHookDefinition
Allows to define hooks on events

The PluginHookDefinition type is an object with each key as an event name and the value is a valid HookEventHandler.

export type PluginHookDefinition = {
  /**
   * Event name or wildcard event.
   */
  [event: string]: HookEventHandler | HookEventHandler[]
}
Deprecated since 2.8.0

A hook handler can also be given as the name of one of the plugin's methods (a string). This form is deprecated, and Kuzzle prints a deprecation warning when it registers the handler: pass the function instead.

imports #

Available since 2.20.2

This property allows to define plugin features.

TypeDescription
ImportConfig
Mappings, roles, profiles and users to import when Kuzzle starts

Kuzzle merges the imports of every plugin, then merges the application imports (set with BackendImport) over them, and imports the result at startup.

class MyPlugin extends Plugin {
  constructor () {
    super({ kuzzleVersion: '>=2.8.0 <3' });

    this.imports = {
      roles: {
        mailer: {
          controllers: { 'my-plugin/mail': { actions: { send: true } } },
        },
      },
    };
  }
}

pipes #

This property allows to define plugin features.

TypeDescription
PluginPipeDefinition
Allows to define pipes on events

The PluginPipeDefinition type is an object with each key as an event name and the value is a valid PipeEventHandler.

export type PluginPipeDefinition = {
  /**
   * Event name or wildcard event.
   */
  [event: string]: PipeEventHandler | PipeEventHandler[]
}
Deprecated since 2.8.0

A pipe handler can also be given as the name of one of the plugin's methods (a string). This form is deprecated, and Kuzzle prints a deprecation warning when it registers the handler: pass the function instead.

strategies #

This property allows to define plugin features.

TypeDescription
StrategyDefinition
A valid StrategyDefinition object.

controllers #

Deprecated since 2.8.0
Not available in Typescript

Controllers should be defined in the api property.

This property is not available in Typescript.

TypeDescription
object
Controllers definition object

Example:

class MyPlugin {
  init (config, context) {
    this.controllers = {
      greeting: {
        sayHello: request => `Hello, ${request.input.args.name}`,
        sayGoodbye: 'greetingSayGoodbye'
      }
    };
  }

  async greetingSayGoodbye (request) {
    return `Goodbye, ${request.input.args.name}`
  }
}

routes #

Deprecated since 2.8.0
Not available in Typescript

Routes should be defined in the api property.

This property is not available in Typescript.

TypeDescription
object
Routes definition object

Example:

class MyPlugin {
  init (config, context) {
    this.controllers = {
      greeting: {
        sayHello: request => `Hello, ${request.input.args.name}`
      }
    };

    this.routes = [
      { verb: 'get', path: '/greeting/:name', controller: 'greeting', action: 'sayHello' }
    ];
  }
}