use-plugin

Generic plugin loader functionality for Node.js frameworks.

For use in framework modules to provide a plugin mechanism for extensions. While a simple require in calling code is a good start, this plugin provides some convenience abstractions over vanilla requires so that you can offer a more user-friendly interface.

Support

If you're using this module, feel free to contact us on twitter if you have any questions! :) @senecajs

See the seneca module for an example of practical usage.

Quick example

// myframework.js
module.exports = function() {
  var use = require('use-plugin')({prefix:'foo',module:module})

  return {
    use: function( plugin_name ) {
      var plugin_description == use(plugin_name)
      
      // call the init function to init the plugin
      plugin_description.init()
    }
  }
}

// callingcode.js
var fm = require('myframework')

// this will try to load:
// 'bar', 'foo-bar', './foo', './foo-bar'
// against the framework module, and then the callingcode module
// nice error messages are thrown if there are problems
fm.use('bar')

Install

npm install use-plugin

There's an npm module page for use-plugin.

Usage

The module provides a builder function that you call with your desired options. In particular, you should always set your module, as above.

The builder function returns a plugin loader function that you can use inside your framework. Calling the loader function returns an object with properties that describe the plugin.

In particular, the point of this module is to resolve (via require), the init function of the plugin, so that you can call it in your framework.

Plugins can be loaded in the following ways:

• By name: fm.use('bar')
• By name with options: fm.use('bar', {color:'red'})
• As a function: fm.use(function(){...})
• As a named function: fm.use(function bar(){...})
• As a (named) function with options: fm.use(function bar(){...}, {color:'red'})
• As an object: fm.use({name:'bar', init:function(){...}})
• As a require: fm.use( require('./bar.js' ) )

When loaded as an Object, you must provide at least the name and init function. When loaded as a require note that the returned value can be any of string, function or object, to which the same rules apply. In particular, you need to explicitly provide a name property if you want an explicit name.

Note that plugins cannot have the same names as builtin Node.js modules. You can however change the list of builtin Node.js module names using the system_modules option.

Plugin Name Resolution

The name of the plugin is determined by the following procedure:

• Plugin specified as string: the given string.
• Plugin specified as function: the Function object name, otherwise generate a name.
• Plugin specifed as object: the name property (which is required)

The plugin may also have a tag. This is a separate string that allows multiple plugins with the same name to be loaded, depending on your use-case. To provide a tag, use the name format: name$tag, or provide a tag property on the plugin object or function specification.

Options

When calling the builder function, you can pass:

• module: The module variable of your framework.
• prefix: An optional prefix for plugin names. Aallows your users to drop the prefix and use abbreviated plugin names.
• builtin: Load builtin plugins first from this sub-folder of your framework.
• errmsgprefix: Prefix string for error messages.

Plugin Description Object

If found, an object is returned describing your plugin:

• name : The resolved name of the plugin.
• tag : The resolved tag of the plugin.
• init : The resolved initialization function of the plugin.
• options : Any user-supplied plugin options provided as the second parameter to the created use function.
• callback : Optional user-supplied callback provided as the third parameter to the created use function. You'll have to call this yourself.
• history : The actual require search history. Array of {module:module-path, name:require-path}.
• search : The require paths to search for.
• modulepath : Module path where found.
• requirepath : Require path where found.
• err : Error object, if any.
• found : Internal search entry details.