title: Plugin

Plugin mechanism is a major feature of our framework. Not only can it ensure that the core of the framework is sufficiently streamlined, stable and efficient, but also can promote the reuse of business logic and the formation of an ecosystem. In the following sections, we will try to answer questions such as

• Koa already has a middleware mechanism, why plugins?
• What are the differences/relationship between middleware and plugins?
• How do I use a plugin?
• How do I write a plugin?
• …

Why plugins?

Here are some of the issues we think that can arise when using Koa middleware:

1. Middleware loading is sequential and it is the user’s responsibility to setup the execution sequence since middleware mechanism can not manage the actual order. This, in fact, is not very friendly.
   When the order is not correct, it can lead to unexpected results.
2. Middleware positioning is geared towards intercepting user requests to add additional logic before or after such as: authentication, security checks, logging and so on. However, in some cases, such functionality can be unrelated to the request, for example, timing tasks, message subscriptions, back-end logic and so on.
3. Some features include very complex initialization logic that needs to be done at application startup. This is obviously not suitable for middleware to achieve.

To sum up, we need a more powerful mechanism to manage, orchestrate those relatively independent business logic.

The relationship between middleware, plugins and application

A plugin is actually a “mini-application”, almost the same as an app:

• It contains Services, [middleware] (./ middleware.md), config, [framework extensions] (./ extend.md), etc.
• It does not have separate [Router] (./ router.md) and Controller.
• It does not have plugin.js, it could only define dependencies with others, but could not deside whether other plugin is enable or not.

Their relationship is:

• Applications can be directly introduced into Koa’s middleware.
• When it comes to the scene mentioned in the previous section, the app needs to import the plugin.
• The plugin itself can contain middleware.
• Multiple plugins can be wrapped as an [upper frame] (../ advanced / framework.md).

Using plugins

Plugins are usually added via the npm module:

$ npm i egg-mysql --save

Note: We recommend introducing dependencies in the ^ way, and locking versions are strongly discouraged.

{
  "dependencies": {
    "egg-mysql": "^ 3.0.0"
  }
}

Then you need to declare it in the config / plugin.js application or framework:

// config / plugin.js
// Use mysql plug-in
exports.mysql = {
  enable: true,
  package: 'egg-mysql'
};

You can directly use the functionality provided by the plugin:

app.mysql.query(sql, values);

Configuring plugins

Each configuration item in plugin.js supports:

• {Boolean} enable - Whether to enable this plugin, the default is true
• {String} package -npm module name, plugin is imported via npm module
• {String} path - The plugin’s absolute path, mutually exclusive with package configuration
• {Array} env - Only enable plugin in the specified runtime (environment), overriding the plugin’s own configuration in package.json

Enabling/Disabling plugins

The application does not need the package or path configuration when using the plugins built in the upper framework. You only need to specify whether they are enabled or not:

// For the built-in plugin, you can use the following simple way to turn on or off
exports.onerror = false;

Environment configuration

We also support plugin.{Env}.js, which will load plugin configurations based on Runtime.

For example, if you want to load the plugin egg-dev only in the local environment, you can install it to devDependencies and adjust the plugin configuration accordingly.

// npm i egg-dev --save-dev
// package.json
{
  "devDependencies": {
    "egg-dev": "*"
  }
}

Then declare in plugin.local.js:

// config / plugin.local.js
exports.dev = {
  enable: true,
  package: 'egg-dev'
};

In this way, npm i --production in the production environment does not need to download theegg-dev package.

Note:

• plugin.default.js does not exists. Use local for dev environments.

• Use this feature only in the application layer. Do not use it in the framework layer.

Package name and path

• The package is introduced in the npm style which is the most common way to import
• path is an absolute path introduced when you want to load the plugin from different location such as when a plugin is still at the development stage or not available on npm
• To see the application of these two scenarios, please see [progressive development] (../ tutorials / progressive.md).

// config / plugin.js
const path = require ('path');
exports.mysql = {
  enable: true,
  package: path.join (__ dirname, '../lib/plugin/egg-mysql'),
};

Plugin configuration

The plugin will usually contain its own default configuration, you can overwrite this in config.default.js:

// config / config.default.js
exports.mysql = {
  client: {
    host: 'mysql.com',
    port: '3306',
    user: 'test_user',
    password: 'test_password',
    database: 'test'
  }
};

Specific consolidation rules can be found in [Configuration] (. / Config.md).

Plugin list

• Framework has default built-in plugins for enterprise applications Common plugins:
  • onerror Uniform Exception Handling
  • Session Session implementation
  • i18n Multilingual
  • watcher File and folder monitoring
  • multipart File Streaming Upload
  • security Security
  • development Development Environment Configuration
  • logrotator Log segmentation
  • schedule Timing tasks
  • static Static server
  • jsonp jsonp support
  • view Template Engine
• More community plugins can be found on GitHub egg-plugin.

Developing a plugin

See the documentation plugin development.