Found something wrong or missing? Open an issue!

The module comes with 2 static methods: Gulp.create - Gulp.createClass

The same gulp API methods we know and love: gulp.src - gulp.dest - gulp.task - gulp.watch

And 4 more to bundle/run tasks: gulp.start - gulp.stack - gulp.series - gulp.parallel

Table of contents:

• Setup
• API
  • Static methods
    • Gulp.create
    • Gulp.createClass
  • Instance methods
    • gulp.task
    • gulp.start
    • gulp.series
    • gulp.parallel
    • gulp.stack
• CLI
• REPL

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

2. 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! When no arguments are given after gulpfile the default task will run instead.

3. What about the CLI? Can I just run gulp-runtime 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)'

which will use the first gulpfile.js found excluding node_modules.

Open a new terminal tab and then

gulp-runtime --tasks default watch serve

When you require the module

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

you get a constructor with two methods Gulp.create and Gulp.createClass.

function create(Object options)

Gulp.create creates a new 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 make series the default when running tasks

function createClass(Object mixin)

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

Example:

Say we always want to create instances that log and have a REPL.

// myGulpConstructor.js

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

exports = module.exports = Gulp;

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

In addition gulp.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
});

done will be always passed as first argument to the task. It should be used if the task does not return a stream, promise or RxJS observable.

Tasks parameters can also contain use regular expressions

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

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

Task names are set using parth. If you want to know more there you will find more information about how far these can go.

gulp.start can be used in two ways

function start(tasks...)

Runs any number of tasks... given. They will run parallel by default. If the gulp instance was created with wait: true they will in series instead.

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, Math.random()*10);
});

gulp.start(build, 'thing');

Which is good, but still limits gulp.start to the way the tasks were defined. For this reason you can also pass arguments in a more functional way.

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

If tasks is an array, these will run with the given args.... The last argument may not be a function. 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 just runs tasks which is not enough when you only need to compose them. For this reason we need another function that will bundle and run a set of tasks only when called.

Just as tasks dependencies bundles into 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)

The initial aim of this project was to be able to run gulp tasks directly from a REPL. But when that was then possible, one also wants to be able to run the CLI while using the REPL, right?

For this reason each of the gulp cli commands is defined as a task for the instance. This way 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']);

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

When an instance passes repl: true the process running will not exit when all tasks are done, instead it will 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

press enter and you will see a prompt > that will run the tasks defined in the gulpfile

>
> build less compress png

How will tasks run with the REPL?

• 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.