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:

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

const jspmBackend = new Jspm("/path/to/plugins");
const hooker = new PluginHooker(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 => {
        const fluxCapacitors = 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).