---
title: Plugins
---
import EnvBadges from '@theme/EnvBadges';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Plugin based architecture that supports module loading, custom types, scopes, and more.
## Installation
```bash
yarn add @boost/plugin
```
```bash
pnpm add @boost/plugin
```
```bash
npm install @boost/plugin
```
## Preface
The plugin system is comprised of 2 parts -- one for projects or libraries that want plugins, and
the other for plugin authors. [Project owners](#registries) can integrate into the system using a
registry, which is based around the idea of loading plugins from third-party packages or file system
paths. [Plugin authors](#plugins) can create and provide packages that register and hook into the
project.
Our system is generic and robust enough to be integrated into any and all projects, with the ability
to handle multiple plugins in parallel through configuration and setting based approaches.
## Registries
For project authors, we begin by defining a unique plugin type, like "renderer", "engine", "asset",
or simply "plugin" if you're not looking to be creative. We can accomplish this with the
[`Registry`][registry] class, which requires a project name (used as a
[package prefix and scope](#naming-guidelines)), plugin type name, and customizable options.
In our examples moving forward, we will use "renderer" as our plugin type.
```ts
import { Registry, Pluggable } from '@boost/plugin';
export interface Renderable extends Pluggable {
render(): string | Promise;
}
const rendererRegistry = new Registry('boost', 'renderer', {
validate(plugin) {
if (typeof plugin.render !== 'function') {
throw new TypeError('Renderers require a `render()` method.');
}
},
});
export default rendererRegistry;
```
You may have noticed the [`validate`](/api/plugin/interface/RegistryOptions#validate) option above.
This option is required as it forces you to verify a plugin being loaded or registered abides the
contract you expect. In the example above, we expect all our renderers to have a `render` method,
otherwise, what would happen if an "engine" plugin was passed instead? Nothing good.
Besides `validate`, there are a handful of other options that can be passed, based on the
[`RegistryOptions`](/api/plugin/interface/RegistryOptions) interface. For more information on life
cycles, continue to the next [plugins](#plugins) chapter.
## Plugins
For both project owners and plugin authors, we keep talking about plugins, but what exactly is a
plugin? In the context of this system, a plugin is either a plain object, or class instance that
extends [Plugin][plugin], with both abiding a defined contract (the `validate` option). A plugin
must also have a unique [`name`](/api/plugin/interface/Pluggable#name) property, which is typically
the npm package name.
```ts
import { Plugin } from '@boost/plugin';
import { Renderable } from './registry';
export default class Renderer extends Plugin implements Renderable {
// Using private scope
readonly name = '@boost/renderer-example';
render() {
return 'Something rendered here?';
}
}
```
```ts
import { Renderable } from './registry';
const renderer: Renderable = {
// Using public scope
name: 'boost-renderer-example',
render() {
return 'Something rendered here?';
},
};
export default renderer;
```
Now why would we use a class instead of an object, as an object seems much simpler? For 2 reasons,
the 1st being that [`Plugin`][plugin] extends from [`Contract`](./common.mdx#class-contracts), which
allows the plugin to inherit options through its constructor. This automatically happens when
loading plugins from a configuration file.
```ts
import { Blueprint, Schemas } from '@boost/common';
import { Plugin } from '@boost/plugin';
import { Renderable } from './registry';
export interface RendererOptions {
async?: boolean;
}
export default class Renderer extends Plugin implements Renderable {
// ...
blueprint({ bool }: Schemas): Blueprint {
return {
async: bool(),
};
}
}
// Example
const renderer = new Renderer({ async: true });
```
The 2nd reason is for TypeScript, as we can type our [tool](#tool-instances) that is passed to
[life cycles](#life-cycles) -- more specifically, the [`Pluggable`][pluggable] type. More
information on the tool can be found in later chapters.
```ts
import { Plugin } from '@boost/plugin';
import { Renderable } from './registry';
import Tool from './Tool';
export default class Renderer extends Plugin implements Renderable {
// ...
}
```
### Priority
After a plugin is loaded, the current plugins list is sorted based on priority. Priority is simply a
number, in ascending order, that determines the order and precedence of plugins. Priority enables
plugin authors and consumers to "mark" as high or low priority.
Plugin authors can set a priority using the [`priority`](/api/plugin/interface/Pluggable#priority)
property.
```ts
import { Plugin } from '@boost/plugin';
import { Renderable } from './registry';
export default class Renderer extends Plugin implements Renderable {
readonly name = '@boost/renderer-example';
priority = 50;
render() {
return 'Something rendered here?';
}
}
```
```ts
import { Renderable } from './registry';
const renderer: Renderable = {
name: 'boost-renderer-example',
priority: 50,
render() {
return 'Something rendered here?';
},
};
export default renderer;
```
While [consumers can override](#loading-plugins) the priority using the `priority` option.
```ts
rendererRegistry.load('boost-renderer-example', {}, { priority: 50 });
```
> The default priority for all plugins is `100`.
### Life cycles
A life cycle is an optional method on a plugin that is executed at specific points in the life of a
plugin. Currently, plugins support 2 life cycles,
[`startup`](/api/plugin/interface/Pluggable#startup) and
[`shutdown`](/api/plugin/interface/Pluggable#shutdown). Startup is executed after a plugin is loaded
and validated, but before it's registered in the registry. Shutdown on the otherhand is executed
before a plugin is unregistered from the registry.
All life cycles are asynchronouse and receive a [tool](#tool-instances) as its only argument.
```ts
import { Plugin } from '@boost/plugin';
import { Renderable } from './registry';
import Tool from './Tool';
export default class Renderer extends Plugin implements Renderable {
// ...
async startup(tool: Tool) {
// Do something
}
async shutdown(tool: Tool) {
// Do something
}
}
```
```ts
import Tool from './Tool';
const renderer = {
// ...
async startup(tool: Tool) {
// Do something
},
async shutdown(tool: Tool) {
// Do something
},
};
export default renderer;
```
## Modules
Typically plugins are represented as an npm package or file module for easy consumption. This
pattern is first class in Boost, but there are specific requirements to be followed. The 1st is that
all plugin modules _must_ return a factory function from the default index import. Using a factory
function provides the following benefits:
- The return value of the factory may change without breaking the import contract.
- Option objects are passed to the factory, which allows implementors to handle it however they
please.
- Runtime and boostrap based logic is encapsulated within the function.
- Multiple instances can be created from a single imported package.
- Asynchronous aware and compatible.
Using our renderer examples, we would have the following factories. One sync and the other async.
```ts title="@boost/renderer-example/src/index.ts"
import { Renderable } from './registry';
import Renderer, { RendererOptions } from './Renderer';
export default async function (options: RendererOptions): Renderable {
await someProcessThatNeedsToBeAwaited();
return new Renderer(options);
}
```
```ts title="boost-renderer-example/src/index.ts"
import { RendererOptions, Renderable } from './registry';
export default function (options: RendererOptions): Renderable {
return {
name: 'boost-renderer-example',
render() {
if (options.async) {
return Promise.resolve('Ooo, this is a fancy render.');
}
return 'Something rendered here?';
},
};
}
```
### Naming guidelines
You may have noticed in the examples above that we've been referencing both scoped and non-scoped
package names. All plugin packages follow the format of `--` for public
third-party packages, and `@/-` for official project owner packages. A 3rd
format exists for public third-party packages that exist within a scope,
`@/--`.
If the plugin name is "example", and our project name is "boost", and our plugin type is "renderer",
the following package names are valid. _No other formats are supported._
| Package | Name |
| ------------- | ------------------------------- |
| Private/Owner | `@boost/renderer-example` |
| Public | `boost-renderer-example` |
| Scoped public | `@scope/boost-renderer-example` |
All name parts should be in kebab-case and abide the official
[npm package naming guidelines](https://github.com/npm/validate-npm-package-name).
## Loading plugins
Plugins are either asynchronously loaded from an npm package, a relative file system path, or
explicitly passed using the [`Registry`][registry] class. The
[`Registry#load()`](/api/plugin/class/Registry#load) method can be used to load a single plugin,
while [`Registry#loadMany()`](/api/plugin/class/Registry#loadMany) will load multiple. Loading
accepts 3 different formats, which are outlined with the examples below.
Passing a string will load based on module name or file path. Names can either be short (just the
plugin name), or in the long fully qualified form (project, type, and plugin name). When using the
short form, the loader will attempt to find both the scoped (`@boost/renderer-example`) and
non-scoped packages (`boost-renderer-example`), with scoped taking precedence.
```ts
// Load by short module name
const renderer = await rendererRegistry.load('foo');
// Load by long module name with options
const renderer = await rendererRegistry.load('boost-renderer-foo', { async: true });
// Load by file path
const renderer = await rendererRegistry.load('./renderers/qux.js');
```
You may also load many plugins in parallel, by passing an array of module names or plugin instances,
or by passing an object of module names that map to booleans or options.
```ts
// Load many with default options
const renderers = await rendererRegistry.loadMany([
'foo',
'@boost/renderer-bar',
'@scope/boost-renderer-baz',
]);
// Load many with custom options
const renderers = await rendererRegistry.loadMany({
foo: { async: true },
'@boost/renderer-bar': true, // Enabled
'@scope/boost-renderer-baz': false, // Disabled
});
```
And lastly, passing a plugin object directly is also supported.
```ts
const renderer = await rendererRegistry.load({
name: '@scope/boost-renderer-baz',
render() {
return 'Hello world';
},
});
// Or
const renderer = await rendererRegistry.load(new Renderer());
```
Loaded and registered plugins should then be accessed with
[`get()`](/api/plugin/class/Registry#get), [`getMany()`](/api/plugin/class/Registry#getMany), or
[`getAll()`](/api/plugin/class/Registry#getAll), all of which check based on the plugin's `name`
property.
```ts
const renderer = rendererRegistry.get('boost-renderer-foo');
```
### Tool instances
Most projects have a central object or class instance that powers their entire process, for
instance, Webpack has the `Compiler` and `Compilation` instances. In Boost this is called a tool (as
in developer or build tool).
Tools are optional, but when defined, they're passed to plugin life cycles, so that plugins may
interact and integrate with them. For proper type-safety, the Tool type should be passed as a
generic to [`Registry`][registry], [`Plugin`][plugin], and [`Pluggable`][pluggable].
```ts
import { Registry, Pluggable, Plugin } from '@boost/plugin';
import Tool from './Tool';
export interface Renderable extends Pluggable {
render(): string | Promise;
}
class Renderer extends Plugin implements Renderable {}
const registry = new Registry(/* ... */);
const renderer = new Renderer();
```
If you have a tool instance, pass the tool as an option to
[`Registry#load()`](/api/plugin/class/Registry#load) and
[`Registry#loadMany()`](/api/plugin/class/Registry#loadMany).
```ts
import Tool from './Tool';
const tool = new Tool();
await registry.load('foo', {}, { tool });
await registry.loadMany(['foo', 'bar'], { tool });
```
### Configuration files
The loader methods were built to support plugins defined in [configuration files](./config.mdx), as
this is a common use case. Settings to configure plugins are designed with 3 different formats in
mind, all of which can be used together, and will merge into a valid final result.
The first is a simple array of plugin sources (module name or relative file path). When using a
module, both long and short forms are supported.
```js
{
"renderers": [
"foo", // @boost/renderer-foo, boost-renderer-foo
"@boost/renderer-bar",
"@scope/boost-renderer-baz",
"../custom/renderer.js"
]
}
```
```js
module.exports = {
renderers: [
'foo', // @boost/renderer-foo, boost-renderer-foo
'@boost/renderer-bar',
'@scope/boost-renderer-baz',
'../custom/renderer.js',
],
};
```
To expand upon the previous example, an individual plugin can be configured with options by passing
a tuple alongside the source. Plugins can also be disabled by passing a `false` value.
```js
{
"renderers": [
["foo", { "async": true }],
"@boost/renderer-bar",
["@scope/boost-renderer-baz", false], // Disabled
"../custom/renderer.js"
]
}
```
```js
module.exports = {
renderers: [
['foo', { async: true }],
'@boost/renderer-bar',
['@scope/boost-renderer-baz', false], // Disabled
'../custom/renderer.js',
],
};
```
The final format, which is quite advanced, is using an object that maps plugin sources to
configurable options or flags (enable or disable the plugin).
```js
{
"renderers": {
"foo": { "async": true }, // Enabled with options
"@boost/renderer-bar": {}, // Enabled with empty options
"@scope/boost-renderer-baz": false, // Disabled
"../custom/renderer.js": true // Enabled
}
}
```
```js
module.exports = {
renderers: {
foo: { async: true }, // Enabled with options
'@boost/renderer-bar': {}, // Enabled with empty options
'@scope/boost-renderer-baz': false, // Disabled
'../custom/renderer.js': true, // Enabled
},
};
```
> Configuration files are designed to be serializable, so passing class instances (Webpack/Rollup
> style) is not supported. It's also not necessary with our factory pattern!
## Ecosystem
Below are a list of third-party projects and their current plugin implementations. These were used
as a basis and reference for Boost's plugin system.
| Project | Plugin pattern | Options pattern | Package names | Lifecycle events |
| ------------------------------ | ---------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------- | ---------------- |
| [Babel][babel] | Function that returns an object | Function argument | babel-plugin-foo, @babel/plugin-foo | pre(), post() |
| [ESLint][eslint] | Object | | eslint-plugin-foo | |
| [Gulp][gulp] | Function that returns a stream | Function argument | N/A | |
| [Parcel asset][parcel-asset] | Class that extends `Asset` | Constructor | parcel-asset-foo,
@parcel/asset-foo | |
| [Parcel plugin][parcel-plugin] | Function that binds events | | parcel-plugin-foo, @parcel/plugin-foo | |
| [Prettier][prettier] | Named exports | | prettier-plugin-foo, @prettier/plugin-foo, @scope/prettier-plugin-foo | |
| [Rollup][rollup] | Function that returns an object | Function argument | rollup-plugin-foo | Many |
| [Webpack][webpack] | Stand-alone class | Constructor (implementation dependent) | | apply() |
| [Yarn][yarn] | Object with `factory()` that returns an object | | | factory() |
[babel]:
https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md#toc-writing-your-first-babel-plugin
[eslint]: https://eslint.org/docs/developer-guide/working-with-plugins
[gulp]: https://gulpjs.com/docs/en/getting-started/using-plugins
[parcel-asset]: https://parceljs.org/asset_types.html
[parcel-plugin]: https://parceljs.org/plugins.html
[prettier]: https://prettier.io/docs/en/plugins.html
[rollup]: https://rollupjs.org/guide/en/#plugins-overview
[webpack]: https://webpack.js.org/contribute/writing-a-plugin/
[yarn]: https://next.yarnpkg.com/advanced/plugin-tutorial
[plugin]: /api/plugin/class/Plugin
[pluggable]: /api/plugin/interface/Pluggable
[registry]: /api/plugin/class/Registry