Found something wrong or missing? Open an issue!

• Setup
• API
  • Gulp.create
  • Gulp.createClass
  • gulp.task
  • gulp.start
  • gulp.series
  • gulp.parallel
  • gulp.stack
• CLI
• REPL
• Task arguments
• Customizable logging

The module has 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 3 more to bundle/run tasks

gulp.series - gulp.parallel - gulp.stack

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 the default task will run instead.

3. What about the CLI? Can I just run gulp-runtime from the terminal?

Yes. For this 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 in the current working directory excluding node_modules.

Right after this open a new terminal tab and write

gulp-runtime --tasks default watch serve

The module exports a constructor function

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

which has two static methods: Gulp.create and Gulp.createClass.

function create([Object props])

Gulp.create returns a new instance with the given props.

Defaults are:

• props.log = true task logging is enabled, pass false to disable it

• props.repl = false the REPL is disabled, pass true to enable it

• props.wait = false tasks will run in parallel by default. Pass wait: true to make series the default when running tasks

• props.onStackEnd called when a stack has ended, defaults to empty function

• props.onHandleEnd called after a task has ended, defaults to empty function

• props.onHandleStart called before a task starts, defaults to empty function

• props.onHandleError called when a task throws, defaults to empty function

These callbacks can be overridden in gulp.series, gulp.parallel and gulp.stack passing an object as a last argument.

function createClass([Object mixin])

Gulp.createClass returns a new constructor function that inherits from its parent prototype.

• When mixin is given it overrides its parent prototype.
• When mixin.create is given it will be used as the instance constructor.

Example:

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

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

exports = module.exports = Gulp;

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

In addition task names can use :parameters (like expressjs routes) and have arguments passed from other task or task runner.

:parameters 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 use regular expressions using parens right after the parameter

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

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

To know more about how this tasks names can be set see parth.

arguments example:

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

gulp.task('build', function (done, sources, dest) {
  var stream = gulp.src(sources)
    // some build steps here

  stream.on('end', function () {
    // pass stream to next task
    done(stream);
  });
});

gulp.task('minify', function (done, stream) {
  return stream
    // minify
    .pipe(gulp.dest(dest));
});

gulp.task('build and min', function (done) {
  gulp.series('build', 'minify')('src/**/*.js', 'dest/source.min.js', done);
});

Can be used in two ways

function start(tasks...)

Runs any number of tasks... given with the defaults of the instance.

Each of the tasks... can be either a string or a function.

Example:

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

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

gulp.task('thing', function (done){
 setTimeout(done, Math.random()*10);
});

gulp.start(build, 'thing');
// ^ will run in series since the instance was created with `{wait: true}`

function start(Array tasks, args...)

Same as start(tasks...) but passing the args... down to each of the tasks run.

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

series bundles the given tasks... into one async function and returns it. This function will always run the tasks... in series.

Its sugar on top of [gulp.stack][#gulpstack]. See [gulp.stack][#gulpstack] for more information about options.

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

parallel bundles the given tasks... into one async function and returns it. This function will always run the tasks... in parallel.

Its sugar on top of [gulp.stack][#gulpstack]. See [gulp.stack][#gulpstack] for more information about options.

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

stack bundles the given tasks... into one async function and returns it.

Each tasks... can be either a string or a function.

If given, options will override the instance props for this stack.

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 the gulp cli commands are set as tasks for each instance. Which lets one use them as 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 does not exit when all tasks are done. What happens then its that the process will have a REPL listening on stdin.

$ node gulpfile.js

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

>
> build less compress png

For more information about how tasks are run see gulp-repl.

Callbacks passed to the constructor: onHandleStart, onHandleEnd and onHandleError are used to internally to produce logging but they can be overridden at:

• class level with Gulp.createClass
• instance level with Gulp.create
• bunlde/run level using one of the composers (gulp.start, gulp.series, gulp.parallel and gulp.stack).

Example:

var MyGulp = require('gulp-runtime').createCLass({
  onHandleEnd: function (task) {
    console.log('end', task.label);
  },
  onHandleStart: function (task) {
    console.log('start', task.label);
  },
  onHandleError: function (error, task, stack) {
    console.log('error!', task.label);
    throw error;
  }
});

var myGulp = MyGulp.create({
  onHandleStart: function (task) {
    console.log(task.label, 'ended!');
  }
});

myGulp.task(':name', function (done) {
  if (this.params && this.params.name === 'three') {
    throw new Error('ups, something broke');
  } else {
    setTimeout(done, 1000);
  }
});

myGulp.stack('one', 'two', 'three', {
  onHandleError: function (error, task, stack) {
    console.log(task.label, 'is dead');
    console.log(error);
  }
})();

Any of the task runners (gulp.start, gulp.series, gulp.parallel and gulp.stack) can be used to pass arguments down.

var gulp = require('gulp-runtime').create();
var args = [1, 2, 3];

gulp.task(':name', function (done, one, two, three) {
  console.log(one, two, three);
  done(null, one + two + three);
});

// with gulp.stack
gulp.stack('taskNameHere')(1, 2, 3, function (error, result) {
  if (error) {
    console.log('ups, who farted?');
    console.log(error.stack);
  } else {
    console.log('all right, we are done at', result, 'pm today');
  }
});

// with gulp.start
gulp.task('default', function (done) {
  gulp.start(['taskNameHere'], 1, 2, 3, {
    onStackEnd: function (error, result) {
      if (error) {
        console.log('ups, who farted?');
        console.log(error.stack);
      } else {
        console.log('all right, we are done at', result, 'pm today');
      }
      done();
    }
  })
});