gulp-task
Basic Info
Preface
This was written as a wrapper for gulp.task in order to get promise-based dependency management.
The documentation and source is written in coffeescript but it should work with vanilla gulp just the same.
Installation
npm install --save gulp-task
task = require 'gulp-task'
Optionally, you can configure it to automatically register gulp tasks:
taskconfigure gulp
API
This module has 4 functions. Here is the order that you'll most likely use them:
task.configure
task
task.run
task.watch
task.getTaskNames
task.configure(gulp)
This makes it so that when you run task(name, cb), you also register the same task with gulp, enabling command line execution.
task(name, cb)
This registers a new task to later be run via task.run. Dependencies are taken care of via promises.
task.run(name|cb)
This accepts either the name of a previously registered task or an anonymous function.
task.getTaskNames()
This simply returns a sorted list the names of registered tasks.
Notes
task.configure
A Note About Not Running This module was written as a replacement for gulp.task
. You're still free to use gulp.task directly but those tasks registered via gulp.task
will not be visible via task.run
. A usage where you don't run task.configure gulp
might looks something like:
gulp.task 'build', ->
task.run 'compile'
.then -> task.run 'copy'
task 'compile', -> #compile code
task 'copy', -> #copy code
In this case, you'd be able to run coffeegulp build
from command-line but not coffeegulp compile
or coffeegulp copy
.
This "private task" effect is why configuring was made optional.
A Note About Tasks
task.run
returns a Promise
. How that promise is resolved depends on the return value of the function being run.
Regardless of if you're running an anonymous function or calling a registered one by name, the nature of the returned promise falls into three cases.
Case 1: Task Returns a Promise
This is simple enough. task.run
simply returns the promise.
Case 2: Task Returns a Stream
task.run
returns a promise that resolves via .pipe gulpCallback -> resolve stream
Case 3: Task Returns Something Else
In this event, task.run
simply returns a resolved promise after running the task.
.then -> gulp.src
A Note About Let's say that you're defining a task that does some stuff via task.run and then calls .then
on the promise and provides a callback which returns a Stream
.
This would be an issue. The resolve chain would not wait for the gulp.src stream to end before continuing.
This might result in unexpected concurrency and reporting issues.
It's important to wrap streams in a task.run ->
when being called from within a .then ->
.
Acceptable
task 'copy'-> gulpsrc'src' pipe gulpdest 'dest'
task 'build'-> taskrun 'compile' then -> taskrun 'copy'
task 'build'-> taskrun 'compile' then -> taskrun -> gulpsrc'src' pipe gulpdest 'dest'
task 'build'-> taskrun 'compile' then -> somethingSynchronous
task 'watch'-> taskrun 'compile' then -># Warning: This is over-simplified and potentially problematic. # See "Watch Example" below for more info. gulpwatch 'src/**/*.coffee'-> taskrun 'compile'
Not Acceptable
task 'build'-> taskrun 'compile' then -> gulpsrc'src' pipe gulpdest 'dest'
Examples
Semi-Realistic Stream Example
gulpfile.coffee
task = require 'gulp-task'gulp = require 'gulp'coffee = require 'gulp-coffee'jade = require 'gulp-jade'rimraf = require 'gulp-rimraf'Promise = require 'bluebird'taskconfigure gulp task 'refresh'-> taskrun 'clean' then -> taskrun 'compile' task 'clean'-> gulpsrc 'bin'read: false pipe rimraf task 'compile'-> Promiseall taskrun 'compile:coffee' taskrun 'compile:jade' task 'compile:coffee'-> gulpsrc "src/**/*.coffee" pipe coffee pipe gulpdest 'bin' task 'compile:jade'-> gulpsrc "src/**/*.jade" pipe jade pipe gulpdest 'bin'
Output
$ coffeegulp rebuild[gulp] Using gulpfile ~/Documents/GitProjects/gulp-task/gulpfile.coffee[gulp] Starting 'rebuild'...[task] Running 'rebuild'[task] Running 'clean'[task] Finished 'clean' in 11.546 ms[task] Running 'compile'[task] Running 'compile:coffee'[task] Running 'compile:jade'[task] Finished 'compile:coffee' in 56.239 ms[task] Finished 'compile:jade' in 53.605 ms[task] Finished 'compile' in 56.998 ms[task] Finished 'rebuild' in 69.254 ms[gulp] Finished 'rebuild' after 69 ms
Hello World
gulpfile.coffee
task = require 'gulp-task'gulp = require 'gulp'taskconfigure gulp task 'default'-> taskrun 'hello' task 'hello'-> consolelog 'Hello World!'
Output
$ coffeegulp[gulp] Using gulpfile ~/Documents/GitProjects/gulp-task/gulpfile.coffee[gulp] Starting 'default'...[task] Running 'default'[task] Running 'hello'Hello World![task] Finished 'hello' in 1.244 ms[task] Finished 'default' in 1.728 ms[gulp] Finished 'default' after 1.91 ms
Basic Stream
gulpfile.coffee
task = require 'gulp-task'gulp = require 'gulp'coffee = require 'gulp-coffee'gulp = require 'gulp'taskconfigure gulp task 'compile'-> gulpsrc "src/**/*.coffee" pipe coffee pipe gulpdest 'bin'
Output
$ coffeegulp compile[gulp] Using gulpfile ~/Documents/GitProjects/gulp-task/gulpfile.coffee[gulp] Starting 'compile'...[task] Running 'compile'[task] Finished 'compile' in 22.872 ms[gulp] Finished 'compile' after 23 ms
task.watch
Basic gulpfile.coffee
task = require 'gulp-task'gulp = require 'gulp'coffee = require 'gulp-coffee'gulp = require 'gulp'taskconfigure gulp task 'compile'-> gulpsrc "src/**/*.coffee" pipe coffee pipe gulpdest 'bin' task 'watch'-> taskrun 'compile' then -> taskwatch 'src/**/*.coffee'-> taskrun 'compile'
Output
$ coffeegulp watch[gulp] Using gulpfile ~/Documents/GitProjects/gulp-task/gulpfile.coffee[gulp] Starting 'watch'...[task] Running 'watch'[task] Running 'compile'[task] Finished 'compile' in 14.42 ms[task] Finished 'watch' in 20.66 ms[gulp] Finished 'watch' after 21 ms<MADE CHANGE>[task] Running 'compile'[task] Finished 'compile' in 3.800 ms
Running Tasks in Series / Using Promises
gulpfile.coffee
task = require 'gulp-task'gulp = require 'gulp'taskconfigure gulpPromise = require 'bluebird' task 'series'-> taskrun 'a' then -> taskrun 'b' then -> consolelog 'We Are Done' task 'a'-> setTimeout -> consolelog 'Task A!' resolve 1500 task 'b'-> setTimeout -> consolelog 'Task B!' resolve 2000
Output
$ coffeegulp series[gulp] Using gulpfile ~/Documents/GitProjects/gulp-task/gulpfile.coffee[gulp] Starting 'series'...[task] Running 'series'[task] Running 'a'Task A![task] Finished 'a' in 1.502 s[task] Running 'b'Task B![task] Finished 'b' in 2.001 sWe Are Done[task] Finished 'series' in 3.504 s[gulp] Finished 'series' after 3.5 s
Running Tasks in Parallel / Using Promises
gulpfile.coffee
task = require 'gulp-task'gulp = require 'gulp'taskconfigure gulpPromise = require 'bluebird' task 'parallel'-> Promiseall taskrun 'a' taskrun 'b' then -> consolelog 'We Are Done' task 'a'-> setTimeout -> consolelog 'Task A!' resolve 1500 task 'b'-> setTimeout -> consolelog 'Task B!' resolve 2000
Output
$ coffeegulp parallel[gulp] Using gulpfile ~/Documents/GitProjects/gulp-task/gulpfile.coffee[gulp] Starting 'parallel'...[task] Running 'parallel'[task] Running 'a'[task] Running 'b'Task A![task] Finished 'a' in 1.502 sTask B![task] Finished 'b' in 2.002 sWe Are Done[task] Finished 'parallel' in 2.003 s[gulp] Finished 'parallel' after 2 s