gulp-pilot

What is this all about?

Well, are you using Gulp? Did you ever had the problem, that your gulpfile.js gets really big and messy? Or did you need configuration, depending on environment (development, production, etc.)?

Gulp-Pilot aims to solve those obstacles. No more gulp-spaghetti tasks, keeping your tasks DRY, clear and structured.

Installation

Install gulp-pilot as a development dependency:

npm install --save-dev gulp-pilot

Usage

After you have installed this plugin you can utilize it in your gulpfile.js.

Basically tasks are just javascript modules, though you can also group tasks and have multiple tasks defined in one module (subtasks).

Let's assume the following folder structure:

|-- dist/
|-- node_modules/
|-- src/
    |-- ...
|-- gulp/
    |-- foo.js
    |-- bar.js
|-- gulpfile.js
|-- package.json
|-- README.md

Task implementation factories

Those are just functions you would export out of your module, who return a function that implements the task. Each factory gets invoked with 3 parameters:

• gulp - The gulp instance
• $ - The gulp-load-plugins instance hash.
• [config] - The default config, a specified config, or a merged version of both (optional).

gulp/foo.js

module.exports = function(gulp, $, config) {
    return function() {
        return gulp.src('Yours glob pattern here')
            .pipe('...')
            .pipe(gulp.dest('your path here');
    };
}

gulp/bar.js

module.exports = function(gulp, $, config) {
    return function() {
        return gulp.src('Another glob pattern here')
            .pipe('...')
            .pipe(gulp.dest('Another path here');
    };
}

gulpfile.js

var gulp = require('gulp');
var pilot = require('gulp-pilot');
 
pilot.task('foo');
 
pilot.task('bar', ['foo'])

Subtasks

Those are just functions you would export out of your module, who return plain object literals. Who's Properties represent one subtask's implementation.

Each subtask is selected by the colon (:) delimiter in your name, e.g. "filename:subtask". Nesting is possible like "filename:namespace:subtask".

Even paths are supported, like "path/filename", "path/filename:subtask" or "path/filename:namespace:subtask"

gulp/foo.js

module.exports = function(gulp, $, config) {
    return {
        sub1: function() {
            return gulp.src('Yours glob pattern here')
                .pipe('...')
                .pipe(gulp.dest('your path here');
        },
 
        sub2: function() {
            return gulp.src('Yours glob pattern here')
                .pipe('...')
                .pipe(gulp.dest('your path here');
        }
    };
}

gulp/bar.js

module.exports = function(gulp, $, config) {
    return function() {
        gulp.src('Another glob pattern here')
            .pipe('...')
            .pipe(gulp.dest('Another path here');
    };
}

gulpfile.js

var gulp = require('gulp');
var pilot = require('gulp-pilot');
 
pilot.task('foo:sub1');
pilot.task('foo:sub2');
 
gulp.task('foo', ['foo:sub1', 'foo:sub2']);
 
pilot.task('bar', ['foo'])

Configuration

Optionally you can have a config hash available for each task. Gulp-Pilot always scans your root directory for <package.name>.conf.{js|json} file, which will be the default config, see following examples:

project.conf.js

module.exports = {
    path: {
        src: 'src/',
        dist: 'dist',
    }
};

project.conf.json

{
    "path": {
        "src": "src/",
        "dist": "dist/"
    }
}

CLI Options

If you need to load different config files, e.g. one for production, the other for development. You can, either by merging with your default config, or without merging.

# custom config, will merge by default (you can change this in your `pilotrc` file) 
gulp [any task] -c custom.conf.js
 
# force merging 
gulp [any task] -c custom.conf.js -m
 
# avoid mergin 
gulp [any task] -c custom.conf.js -i

Flag	Description	Type
--help	Show help	boolean
--config, -c	Load a config file by path - for relative paths see CWD and __dirname below	string
--merge-default-config, -m	Just use this flag to merge supplied config with default config	boolean
--ignore-default-config, -i	Just use this flag to ignore default config (no merging)	boolean

API Documentation

Classes

GulpPilot

Members

settings : Settings

Typedefs

TaskToken : string

The complete name of the task. Subtasks are separated by a colon (:).

InitHash : Object.<string, (GulpPilot~InitCallback|GulpPilot~InitPlugin)>

A hash of property paths who's values are functions implementing a custom initialization behavior.

MergerHash : Object.<string, (GulpPilot~MergerCallback|GulpPilot~MergerPlugin)>

A hash of property paths who's values are functions implementing a custom merge behavior.

GulpPilot

Kind: global class

• GulpPilot
  • new GulpPilot()
  • instance
    • .task(name, [dependencies]) ⇒ GulpPilot
    • .get(name) ⇒ function
  • static
    • .config
    • .gulp
  • inner
    • ~InitCallback : function
    • ~InitPlugin : string
    • ~MergerCallback : function
    • ~MergerPlugin : string
    • ~Settings : Object

new GulpPilot()

GulpPilot helps you to manage you build tasks in separate, well structured files.

Usage: Every task's factory function is invoked with the following 3 parameters:

• gulp - The gulp instance
• $ - The gulp-load-plugins instance hash.
• [config] - The default config, a specified config, or a merged version of both (optional).

Peer-Dependencies: This plugins requires your package to use gulp, gulp-util and gulp-load-plugins.

Note: Your default config is always in your root folder called <package.name>.conf.{js,json}.

CLI-Options:

Flag	Description	Type
--help	Show help	boolean
--config, -c	Load a config file by path - for relative paths see CWD and __dirname below	string
--merge-default-config, -m	Just use this flag to merge supplied config with default config	boolean
--ignore-default-config, -i	Just use this flag to ignore default config (no merging)	boolean

gulpPilot.task(name, [dependencies]) ⇒ GulpPilot

Will add a new gulp task by grabbing the task's function implementation automatically from a JS file with the gulp/ folder.

Kind: instance method of GulpPilot
Returns: GulpPilot - Returns itself to enable method chaining.

Param	Type	Description
name	TaskToken	The name of the task.
[dependencies]	Array	An array of task names to be executed and completed before your task will run.

Example (Utilizing task factories)

 
// example folder structure:
//
// |-dist/
// |-node_modules/
// |-src/
// |  |-...
// |-gulp/
// |  |- foo.js
// |  |- bar.js
// |-gulpfile.js
// |-package.json
// |-README.md
 
// in your gulpfile.js
var pilot = require('gulp-pilot');
 
// will load from gulp/foo.js
pilot.task('foo');
// will load from gulp/bar.js with dependency 'foo'
pilot.task('bar', ['foo']);

Example (Utilizing sub tasks)

 
// in your gulpfile.js
var pilot = require('gulp-pilot');
 
// will load from gulp/foo.js
pilot.task('foo:sub');
// will load from gulp/bar.js with dependency 'foo:sub'
pilot.task('bar', ['foo:sub']);

gulpPilot.get(name) ⇒ function

Get a task's function implementation by name.

Note: This is handy if you want your task name being different from your implementation factory file.

Important: If you supply a deeper subtask nesting than you object literal return by your factory can handle, your task implementing function will have the rest of name applied as it's arguments.

Kind: instance method of GulpPilot
Returns: function - Returns the function that implements the task.

Param	Type	Description
name	TaskToken	The name of the task.

Example (Utilizing task factories)

 
// example folder structure:
//
// |-dist/
// |-node_modules/
// |-src/
// |  |-...
// |-gulp/
// |  |- foo.js
// |  |- bar.js
// |-gulpfile.js
// |-package.json
// |-README.md
 
// in your gulpfile.js
var gulp = require('gulp');
var pilot = require('gulp-pilot');
 
// will load from gulp/foo.js
gulp.task('foo', pilot.get('foo'));
// will load from gulp/bar.js with dependency 'foo'
gulp.task('bar', ['foo'], pilot.get('bar'));

Example (Utilizing sub tasks)

 
// in your gulpfile.js
var gulp = require('gulp');
var pilot = require('gulp-pilot');
 
// will load from gulp/foo.js
gulp.task('foo', pilot.get('foo:sub'));
// will load from gulp/bar.js with dependency 'foo'
gulp.task('bar', ['foo'], pilot.get('bar'));

GulpPilot.config

Export config literal.

Kind: static property of GulpPilot
Properties

Type	Description
object	The loaded config for your project.

GulpPilot.gulp

Export gulp (mainly for run-sequence).

Kind: static property of GulpPilot
See: https://www.npmjs.com/package/run-sequence#using-within-gulp-submodules
Properties

Type	Description
object	The gulp instance used by gulp-pilot.

GulpPilot~InitCallback : function

This callback is executed for a property path that matches. It's up to you what ever initialization implementation you choose for a specific config property.

Kind: inner typedef of GulpPilot

Param	Type	Description
config	Object	The default or custom config object.

GulpPilot~InitPlugin : string

This string is the name of a NPM package which returns a GulpPilot~InitCallback function either directly or as an object literal by init property. It's name format is "gulp-pilot-init-..."

So far there exist the following plugins:

• Preprocess Merger ("gulp-pilot-merger-preprocess")
• Preprocess Topo Merger ("gulp-pilot-merger-preprocess-topo")

You can also search for plugins by gulp-pilot-init keyword. https://www.npmjs.com/search?q=gulp-pilot-merger

Kind: inner typedef of GulpPilot

GulpPilot~MergerCallback : function

This callback is executed for a property path that matches. It's up to you what ever merge implementation you choose for a specific config property.

Kind: inner typedef of GulpPilot

Param	Type	Description
config	Object	The custom config object.
defaultConfig	Object	The default config object.

GulpPilot~MergerPlugin : string

This string is the name of a NPM package which returns a GulpPilot~MergerCallback function either directly or as an object literal by merger property. It's name format is "gulp-pilot-merger-..."

So far there exist the following plugins:

• Preprocess Merger ("gulp-pilot-merger-preprocess")
• Preprocess Topo Merger ("gulp-pilot-merger-preprocess-topo")

You can also search for plugins by gulp-pilot-merger keyword. https://www.npmjs.com/search?q=gulp-pilot-merger

Kind: inner typedef of GulpPilot

GulpPilot~Settings : Object

The default GulpPilot settings.

Note: You can overwrite those with a pilotrc file in your root project folder.

Note: Your default config is always in your root folder called <package.name>.conf.{js,json}

Kind: inner typedef of GulpPilot
Properties

Name	Type	Default	Description
directory	string	"gulp"	The directory where all gulp tasks will be implemented.
packageJSON	string	"package.json"	The name of your projects package.json file.
mergeDefaultConfig	boolean	true	Whether or not to merge custom config with your default config.
init	InitHash	{}	A hash of property paths who's value are functions implementing a custom initialization behavior.
merger	MergerHash	{}	A hash of property paths who's value are functions implementing a custom merge behavior.

settings : Settings

Kind: global variable

TaskToken : string

The complete name of the task. Subtasks are separated by a colon (:).

Kind: global typedef
Example

'foo'
'filename:subtask'
'filename:namespace:subtask'
 
'path/bar'
'path/filename:subtask'

InitHash : Object.<string, (GulpPilot~InitCallback|GulpPilot~InitPlugin)>

A hash of property paths who's values are functions implementing a custom initialization behavior.

Kind: global typedef
Example (Custom init callback)

// your default config => <package.name>.conf.{js,json}
{
 "foo": {
     "a": 1,
     "b": 2
 },
 "bar": "baz"
}
 
// custom config
{
 "foo": {
     "b": 4
 }
}
 
// your pilotrc file
{
 "init": {
     "foo": function(config) { ... }
 }
}

Example (Init Plugin)

// your default config => <package.name>.conf.{js,json}
{
 "foo": {
     "a": 1,
     "b": 2
 },
 "bar": "baz"
}
 
// custom config
{
 "foo": {
     "b": 4
 }
}
 
// your pilotrc file
{
 "init": {
     "foo": "gulp-pilot-init-<name of merger plugin here...>"
 }
}

MergerHash : Object.<string, (GulpPilot~MergerCallback|GulpPilot~MergerPlugin)>

A hash of property paths who's values are functions implementing a custom merge behavior.

Kind: global typedef
Example (Custom merger callback)

// your default config => <package.name>.conf.{js,json}
{
 "foo": {
     "a": 1,
     "b": 2
 },
 "bar": "baz"
}
 
// custom config
{
 "foo": {
     "b": 4
 }
}
 
// your pilotrc file
{
 "merger": {
     "foo": function(config, defaultConfig) { ... }
 }
}

Example (Merger Plugin)

// your default config => <package.name>.conf.{js,json}
{
 "foo": {
     "a": 1,
     "b": 2
 },
 "bar": "baz"
}
 
// custom config
{
 "foo": {
     "b": 4
 }
}
 
// your pilotrc file
{
 "merger": {
     "foo": "gulp-pilot-merger-<name of merger plugin here...>"
 }
}

License

The MIT License (MIT)

Copyright (c) 2016 Andreas Deuschlinger

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.