README

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, (GulpPilotInitCallback|GulpPilotInitPlugin)>`

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, (GulpPilotMergerCallback|GulpPilotMergerPlugin)>`

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)

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.

Usage no npm install needed!

README

What is this all about?

Installation

Usage

Task implementation factories

Subtasks

Configuration

CLI Options

API Documentation

Classes

Members

Typedefs

GulpPilot

new GulpPilot()

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

gulpPilot.get(name) ⇒ function

GulpPilot.config

GulpPilot.gulp

GulpPilot~InitCallback : function

GulpPilot~InitPlugin : string

GulpPilot~MergerCallback : function

GulpPilot~MergerPlugin : string

GulpPilot~Settings : Object

settings : Settings

TaskToken : string

InitHash : Object.<string, (GulpPilotInitCallback|GulpPilotInitPlugin)>

MergerHash : Object.<string, (GulpPilotMergerCallback|GulpPilotMergerPlugin)>

License

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

gulpPilot.get(name) ⇒ `function`

GulpPilot~InitCallback : `function`

GulpPilot~InitPlugin : `string`

GulpPilot~MergerCallback : `function`

GulpPilot~MergerPlugin : `string`

GulpPilot~Settings : `Object`

settings : `Settings`

TaskToken : `string`

InitHash : `Object.<string, (GulpPilotInitCallback|GulpPilotInitPlugin)>`

MergerHash : `Object.<string, (GulpPilotMergerCallback|GulpPilotMergerPlugin)>`