gulpplug

A toolkit for gulp, which can require task files, auto-load gulp plugins and offer some sugar.

README IN PROGRESS

• About gulpplug
• Install
• Quick Start
• Usage
  • Create your Plug instance
  • Options
  • Defining Tasks
  • Help task and descriptions
  • Loading gulp plugins
  • Plug Class
• License

About gulpplug

gulpplug's main purpose is to glob some files and require them to create gulp tasks. This way you can organize your tasks in multiple files and folders. You can also define task descriptions from which gulpplug can create a help task listing all available tasks.

Within your task function context you can access your current instance of Plug, gulpplug's main class, via this and find gulp at this.gulp. gulpplug also offers gulp-util (this.util), run-sequence (this.runSequence) and your gulp plugins (this.plugins), which can be auto-loaded using auto-plug.

Install

gulpplug doesn't include gulp and is useless without it, so you obviously have to install both. Use npm:

npm i -S gulp gulpplug

Quick Start

Your Gulpfile.js could look like this:

var gulp = require('gulp'),
    plug = require('gulpplug')(gulp);

plug.loadPlugins()
    .addTasks()
    .addHelpTask();

Let's say, you want to create a gulp task called minify to pipe some javascript files through gulp-uglify, which you have installed as dependency.

Go ahead and create the file .gulpplug/minify.js containing:

module.exports = function() {
    return this.gulp.src('./src/*.js')
        .pipe(this.plugins.uglify())
        .pipe(this.gulp.dest('./dist'));
}

Usage

Create your Plug instance

Plug is gulpplug's main class. It needs your current gulp instance as first argument and accepts an options object as second argument.

You can create your Plug instance by calling the required main function…

var gulp = require('gulp'),
    plug = require('gulpplug')(gulp);

…or require the class definition and call new:

var gulp = require('gulp'),
    Plug = require('gulpplug').Plug
    plug = new Plug(gulp);

Options

gulpplug looks for a folder called .gulpplug/ in the same directory where your Gulpfile.js is.

See also example/.

Defining Tasks

All files matching **/*.js within .gulpplug/ will be required and should return a function to create a task.

For example, .gulpplug/foo.js will be executable via gulp foo and could look like this:

module.exports = function() {
    return this.gulp.src(…)
        .pipe(this.plugins.someGulpPlugin())
        .pipe(this.gulp.dest(…));
    });
};

this is your current Plug instance, delivering gulp, gulp-util and run-sequence as properties. (As well as other properties and methods you may want to use - take a look at the sourcecode.)

module.exports = function(done) {
    this.util.log(this.chalk.green('Starting async things…'));
    setTimeout(function() {
        this.util.log(this.chalk.red('Async stuff done.'));
        done();
    }.bind(this)), 100);
};

You can organize your task files in subfolders.
For example, this will add the tasks foo and bar:baz:

my-project/
 ├─╸ .gulpplug/
 │    ├─╸ bar/
 │    │    └─╸ baz.js
 │    └─╸ foo.js
 └─╸ Gulpfile.js

Help task and descriptions

You can add a automatically generated help task by calling plug.addHelpTask().

Run the task via gulp help. It will show all available tasks with a description if available.

Add a task description:

module.exports = [
    'this task does awesome stuff',
    function() {
        …
    }
];

Loading gulp plugins

By calling plug.loadPlugins(), auto-plug will be used to load gulp plugins defined in your project's package.json. You can set auto-plug options as first argument.

Plug Class

By calling require('gulpplug')(…) you get a new instance of Plug, which expects gulp as first argument and an optional options object as second argument.

You can also access the class directly.

var path = require('path'),
    gulp = require('gulp'),
    Plug = require('gulpplug').Plug,
    plug = new Plug(gulp, {
        cwd: path.dirname(__filename),
        tasksDir: 'my-gulp-tasks'
    });

License

MIT © 2015 Simon Lepel