Find something missing? Open an issue

API - REPL - instances - task params - async composers

1. You don't know gulp? First go here

2. Install npm install --save-dev gulp-runtime

3. Open a gulpfile (or create one) and change this line

var gulp = require('gulp');

with

var gulp = require('gulp-runtime').create();

After that run the gulpfile with node directly from the command line

node gulpfile.js default watch serve

Thats it! If no arguments are given after the gulpfile the default task will run instead.

4. What about the CLI? Can I run gulp from the terminal?

Yes. Just add an alias to your .bashrc/.zshrc

alias gulp-runtime='node $(find . -name "gulpfile.js" -not -path "./node_modules/*" | head -n1)'

(or change it to your preferences). With that you can use

gulp-runtime --tasks default watch serve

directly from the terminal.

5. And what about CLI commands like --tasks, --version, etc.?

Each of the gulp cli commands is defined as a task for the instance. So you can use these as you would with normal tasks.

Example:

var gulp = require('gulp-runtime').create();

gulp.task('info', ['--tasks', '--version']);
// other tasks...
gulp.task('default', ['info']);

The module comes with the same gulp API methods we know and love

gulp.src - gulp.dest - gulp.task - gulp.watch

and 4 more

gulp.start - gulp.stack - gulp.series - gulp.parallel

When you require the module

var Gulp = require('gulp-runtime');

you get a constructor

function create(Object options)

Gulp.create creates a new gulp instance with the given options. These options default to:

• options.log = true if false the instance will have no logging
• options.repl = false no REPL by default
• options.wait = false tasks run in parallel by default. Pass wait: true to run tasks in series

function createClass(Object mixin)

Gulp.createClass creates a new Gulp class with the given mixin mixed in with its parent prototype. If mixin.create is given it will be used as constructor.

Example:

var Gulp = require('gulp-runtime').createClass({
  create: function Gulp (options) {
    options = options || {};
    options.log = true;
    options.repl = true;
    Gulp.super_.call(this, options);
  }
})

gulp.src, gulp.dest, gulp.watch and gulp.task behave the same as described in the gulp API documentation.

In addition gulp.task task names can also have :parameters (like expressjs routes).

Example:

var gulp = require('gulp-runtime').create();

gulp.task('build:mode', function (done) {
  console.log(this.params.mode);
  done(); // or do async things
});

or even have regular expression right after the parameter

var gulp = require('gulp-runtime').create();

gulp.task('build:mode(-dev|-prod)', function (done){
  done(); // or do async things
});

The parameters are defined using parth. There you will find more information about what qualifies as parameter and what not.

gulp.start can be used in two ways

function start(tasks...)

Runs any number of tasks... given in parallel.

tasks... can be either a string (matching one of the tasks registered) or a function.

Example:

var gulp = require('gulp-runtime').create();

function build(done){
  done(); // or do async things
}

gulp.task('thing', function (done){
 setTimeout(done, 100);
});

gulp.start(build, 'thing');

Or, in order to give arguments to the tasks, you can use

function start(Array tasks, args...[, onStackEnd])

If tasks is an array it will be taken as the tasks to run and the rest of arguments are passed down. If the last argument is a function it will be called when all of the given tasks are finished.

var gulp = require('gulp-runtime').create();

function build(done, a, b){
  done(); // or do async things
}

gulp.task('watch-serve', function (done, a, b){
 done(); // or do async things
});

gulp.task('build dev', function (done, a, b){
  gulp.start([build, 'watch-serve'], a, b, done);
  // done will be called when all of the tasks have ended or there is an error
});

gulp.task('default', function (done) {
  gulp.start(['build dev'], 'a', 'b', done);
  // or
  // gulp.series('build dev')('a', 'b', done);
  // or
  // gulp.parallel('build dev')('a', 'b', done);
});

gulp.start is not enough when you need to compose tasks since it runs them. If you want to compose tasks, you need another function that will run a set of tasks.

So, just as tasks dependencies bundle in one task others, we have 3 async composer functions to help with this (in fact there is only one function and two others are sugar on top).

function series(tasks...[, Object options])

gulp.series stacks the given tasks... into one function and returns it. This function always runs all of the defined tasks... in series.

Its sugar on top of [gulp.stack][#gulpstack] to force the tasks to be run in series.

function parallel(tasks...[, Object options])

gulp.series stacks the given tasks... into one function and returns it. This function always runs all of the defined tasks... in parallel.

Its sugar on top of [gulp.stack][#gulpstack] to force the tasks to be run in series.

function stack(tasks...[, Object options])

gulp.stack stacks the given tasks... into one function and returns it. A function which by default runs them in parallel.

tasks... can be either strings or functions options determines how logging and errors are handled or tasks can be run

• options.wait, default false for parallel, true if tasks should run in series
• options.onHandleStart if given, will run before a task is run
• options.onHandleEnd if given, will run after a task has ended
• options.onHandleError if given, will run when a task errors
• options.onStackEnd if given, will run when all of the stacked functions have ended (including error)

var gulp = require('gulp-runtime').create({repl: true});

When an instance passes repl: true the process running will not stop but wait and have a REPL listening on stdin. This way you can run tasks in the same way you run commands on the terminal.

node gulpfile.js
# some task logging here...
# when done press enter
> build less compress png

• If those tasks are defined they will run in parallel
• If there is more than one instance with repl: true the REPL will go through them and run the first task that matched one of those tasks
• If one or more of those tasks is not defined there will be a warning and none of the tasks will run for that instance of any of the other ones

Exactly, instances. That means that you can split builds into instances within the same process and run them separately. Which is a bit better than taking care of naming or spin another process to run them separated. This is also better for performance since all of the modules that may be used by other build can be reused.

The down side is that the REPL will run the first matching task from those instances that use a REPL.