plugin-hooker

A collection of tools for loading extensions into a JavaScript application.

Installation

Plugin Hooker is on npm; You can install it from there.

npm i --save plugin-hooker

Usage

Typically, you may want to configure the library with the included
JSPM plugin loader:

importPluginHookerfrom'plugin-hooker';

import{Jspm}from'plugin-hooker/backends';

constjspmBackend=newJspm("/path/to/plugins");

consthooker=newPluginHooker(jspmBackend);

Then, use the PluginHooker instance to grab a list of
all the extensions it can find using the backend that
implement a given hook:

// Get a promise to a list extensions that implement a

// particular hook

hooker.load("your-app.namespace.hooks.flux-capacitors")

.then(fluxCapacitorExtensions=>{

constfluxCapacitors= fluxCapacitorExtensions

.map(ext=>ext.value);

doSomethingWith(fluxCapacitors);

})

Each extension is an object with the following shape:

interface Extension {

// A unique identifier for the package the extension was loaded from

packageId: string;

// A name identifying the extension within the module

name: string;

// The actual extension object

value?: any;

// This is filled when there was an error loading the extension

error: Error

}

Alternatively, you can watch the plugin folder for changes an emit
a list of Extension objects initially and then every time the plugin
folder changes:

hooker.watch("hooks:cars")

.subscribe(carExtensions=>{

// This is called every time the plugin folder changes with the

// full list of loaded extensions from this hook.

updateCarList(carExtensions.map(ext=>ext.value));

});

You can stop watching the folder at any time:

hooker.stopWatching()

JSPM backend details

The JSPM backend uses a JSPM beta (0.17) package root as its
plugin folder. This folder must contain a package.json file
and a JSPM configuration file (typically jspm.config.js).
Both of these can be generated by running the command:

jspm init

and following the prompts.

Essentially, plugins are loaded from jspm_packages, and must be
installed using the jspm beta CLI tool (or API). They are packages
except that their package.json file must contain an extensions
entry listing hook implementations. Each entry in the list must take the
following shape:

interface Extension {

// The name of the hook that the extension implements

hook: string;

// The full module name in which the implementation resides

module: string;

// The name of the module export that contains the implementation

// if not given, the default export is used.

export?: string;

}

Here's an example:

{

"extensions":[

{

"hook":"example.hooks.cars",

"module":"this-package/cars/toyota",

"export":"camry"

},

{

"hook":"example.hooks.cars",

"module":"this-package/cars/toyota",

"export":"prius"

},

{

"hook":"example.hooks.formatters",

"module":"this-package/formatters/json",

}

]

}

Caveats

Since this backend requires that plugins are installed
into the plugin folder using the JSPM beta, you must
determine a strategy for doing so yourself. JSPM allows
installation from both npm and github sources.

Also note that unlike JSPM itself, this backend
functions only in a node (including Electron) environment;
it does not work in the browser.

Lastly, only one of these backends may be used in the same
process; any more than that and you will encounter strange behavior.
This means that you will only be able to load plugins from a
single location using this backend.

Once you can get around these, JSPM is a great option as it
provides full dependency resolution and allows dependencies to
be installed side by side.

Custom backend

In case the JSPM backend does not meet your needs, then
you may supply your own backend for loading packages.
For example you may write a simple backend that loads concatenated
JavaScript bundles as plugins.

To do this, you need to implement the IPackageFinder interface
which is provided in TypeScript through this import (the interface
is purely to assist you in development is not available from JavaScript):

import { IPackageFinder } from 'plugin-hooker';

Take a look at src/backends/jspm.ts for an example of how to do this.
(For JavaScript users: only the watch and find methods are required).