node package manager



Auto-require plugin packages by prefix. (for i.e. Gulp, Grunt or other heavy plugin-dependent packages)

npm Package Version MIT License Travis Build Status Code Climate GPA Code Climate Test Coverage

Dependencies Status devDependencies Status


$ npm install auto-plug


auto-plug will return an object containing the required module exports. If your config data (package.json) contains package names like foo-this and foo-that, they can be autoloaded by

var plugins = require('auto-plug')('foo')`

and then accessed by plugins.this()or plugins.that().

Instead of a simple prefix string you can also set custom options:

var plugins = require('auto-plug')({ prefix: 'foo', lazy: false });

with Gulp

Just set the prefix option to gulp:

// Gulpfile.js 
var gulp = require('gulp'),
    gulpPlugins = require('auto-plug')('gulp');
gulp.task('default', function() {
    return gulp
        // ... 

with Grunt

Grunt needs it's own require function:

// Gruntfile.js 
module.exports = function (grunt) {
    require('auto-plug')({ prefix: 'grunt', require: grunt.loadNpmTasks });
    // do grunt things as usual 

with any other thing

… i.e. with Metalsmith:

var metalsmith = require('metalsmith')
    metalsmithPlugins = require('auto-plug')('metalsmith');


If you already loaded your package.json's data, pass it as config option to speed up things:

var pkg = require(process.cwd() + '/package.json'),
    plugins = require('auo-plug')({ prefix: 'foo', config: pkg });


You either have to define a prefix or a pattern and replaceExp. All other options are optional.

  • prefix
    can be used to quickly define pattern and replaceExpr at once (see default options)

  • pattern
    (default: [prefix + '-*', prefix + '.*'])
    a globbing pattern to find packages in config for require

  • replaceExpr
    (default: new RegExp('^' + prefix + '([\.-])'))
    a regular expression for what shall be removed from a package name when adding to container object

  • scope
    (default: ['dependencies', 'devDependencies'])
    which keys in config object contain packages to require

  • module (default: the module that executed require('auto-plug')) The module used to find the default config and requireFn options

  • config
    (default: module option's package.json data)
    the config where auto-plug will look for packages to require; can be a plain object or a string containing a path to require

  • requireFn
    (default: module option's require property)
    the function to be used for requiring packages

  • camelize
    (default: true)
    whether package names should be converted to camelcase when adding to container object or not

  • lazy
    (default: true)
    whether packages should be lazy-loaded (loaded when called for the first time) or directly when calling auto-plug

  • rename
    (default: {})
    a plain object for custom renaming; keys are original package names and values the respective rename string

Default options

    prefix: undefined,
    pattern: [prefix + '-*', prefix + '.*'],
    replaceExpr: new RegExp('^' + prefix + '([\.-])'),
    scope: ['dependencies', 'devDependencies'],
    module: module.parent, // the module that require()'d auto-plug 
    config: findup('package.json', {cwd: path.dirname(this.options.module.filename)}),
    requireFn: this.options.module.require.bind(this.options.module),
    camelize: true,
    lazy: true,
    rename: {}

API Usage

// get your AutoPlug instance 
var AutoPlug = require('auto-plug').AutoPlug,
    autoPlug = new AutoPlug('gulp');
// find matching packages, require them and add them to container 
// manually add a package to container 
// get the container 
var g = autoPlug.getContainer();


MIT © 2014 Simon Lepel