auto-plug
Version:
Auto-require plugin packages by prefix. (for i.e. Gulp, Grunt or other heavy plugin-dependent packages)
200 lines (141 loc) • 5.85 kB
Markdown
auto-plug
=========
> Auto-require plugin packages by prefix. (for i.e. [Gulp](https://github.com/gulpjs/gulp), [Grunt](https://github.com/gruntjs/grunt) or other
> heavy plugin-dependent packages)
[](https://www.npmjs.com/package/auto-plug)
[](http://simbo.mit-license.org)
[](https://travis-ci.org/simbo/auto-plug)
[](https://codeclimate.com/github/simbo/auto-plug)
[](https://codeclimate.com/github/simbo/auto-plug)
[](https://david-dm.org/simbo/auto-plug)
[](https://david-dm.org/simbo/auto-plug#info=devDependencies)
---
<!-- MarkdownTOC -->
- [Install](#install)
- [Usage](#usage)
- [with Gulp](#with-gulp)
- [with Grunt](#with-grunt)
- [with any other thing](#with-any-other-thing)
- [Tip](#tip)
- [Options](#options)
- [Default options](#default-options)
- [API Usage](#api-usage)
- [License](#license)
<!-- /MarkdownTOC -->
## Install
``` bash
$ 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
``` javascript
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](#options):
``` javascript
var plugins = require('auto-plug')({ prefix: 'foo', lazy: false });
```
### with Gulp
Just set the prefix option to `gulp`:
``` javascript
// 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:
``` javascript
// 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](https://github.com/segmentio/metalsmith):
``` javascript
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:
``` javascript
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](#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
``` javascript
{
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
``` javascript
// 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](http://simbo.mit-license.org/)