README.md

auto-plug

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

---

• Install
• Usage
  • with Gulp
  • with Grunt
  • with any other thing
  • Tip
• Options
  • Default options
• API Usage
• License

Install

$ npm install auto-plug

Usage

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
        .src('some/glob')
        .pipe(gulpPlugins.someGulpThing())
        .pipe(gulpPlugins.someOtherGulpThing())
        // ...
    }
});

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');

    Metalsmith
        .source('.')
        .use(metalsmithPlugins.someMetalsmithThing())
        .use(metalsmithPlugins.someOtherMetalsmithThing())
        .build();

Tip

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 });

Options

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
autoPlug.plug();
// manually add a package to container
autoPlug.addPackageToContainer('runSequence');
// get the container
var g = autoPlug.getContainer();

License

MIT © 2014 Simon Lepel