gulp-heap
Semantic gulp API.
Experimental and still under developing, not suitable for production use
A Quick Peek
gulp = require 'gulp'heap = require 'gulp-heap'coffee = heaprequire'gulp-coffee'uglify = heaprequire'gulp-uglify'concat = heaprequire'gulp-concat' gulptask 'coffee' coffee'./coffee/**/*.coffee''./lib/' thenuglify wrapAllwithsourcemapsifclioptsdebug nextconcat'all.js'write'./dist/'
The above gulp task does the following:
- Compile
./coffee/**/*.coffee
then write uglified versions to./lib/
- Generate source maps if
debug
CLI flag is set (runned withgulp coffee --debug
) - Then concat all
.js
files and writeall.js
to./dist
The equivalent code (without CLI arguments handling) in vanilla gulp API would be:
gulp = require 'gulp'gutil = require 'gutil'plumber = require 'gulp-plumber'coffee = require 'gulp-coffee'uglify = require 'gulp-uglify'concat = require 'gulp-concat'sourcemaps = require 'gulp-sourcemaps' gulptask 'coffee'-> gulpsrc'./coffee/**/*.coffee' on'error'gutillog pipeplumber pipesourcemapsinit pipecoffee pipeuglify pipesourcemapswrite pipegulpdest'./lib/' pipeconcat'all.js' pipegulpdest'./dist/'
Installation
$ npm install --save-dev gulp-task
The Patterns
Some patterns are observed in my time of using gulp.
Task Life Cycle
gulpsrcsrc on'error'gutillog # Error handling pipeplumber # Prevent pipe breaking pipetaskopts # Other tasks pipegulpdestdst # Do other stuff
The first called gulp-heap
through task would handle all of that with one line of code:
tasksrcdstopts thenotherTask # Chained API
Sometimes options are needed for gulp.src
or gulp.dest
calls. The equivalent gulp-heap
APIs are:
taskoptssourcesrcsrcOptsdestdstdstOpts # Useful when running mocha tests for example: mochaoptssourcetestSrcread: false
Through Tasks
Tasks that are called once and connected with .pipe
are called through tasks:
filepipetask1pipetask2#...
They can be chained with .then
or .next
call:
# task2 are executed before write to dst task1srcdst thentask2 # ... # task2 are executed after write to dst task2srcdst nexttask2 # ...
Wrapper Tasks
Tasks that are called before and after another task are called wrapper tasks:
file pipewrapperbegin pipetask pipewrapperend
A more cleaned syntax with .with
method:
tasksrcdstwithwrapper
By default, the wrapper will wrap the one through task before it's called. Multiple tasks can be selected with wrap
and wrapAll
methods:
# Wrap task1, task2, task3 with wrapper task1srcdstthentask2thentask3wrapAllwithwrapper # Wrap previous 2 tasks (task2, task3) with wrapper task1srcdstthentask2thentask3wrap2withwrapper
Wrap methods cannot penetrate next
call (the nearest gulp.src
call):
# Only wraps task3 task1srcdstthentask2nexttask3wrapAllwithwrapper# Throws a RangeError task1srcdstthentask2nexttask3wrap2withwrapper
Conditional Tasks
Sometimes you will want to toggle some tasks with bool values (i.e from CLI):
file = gulpsrcsrcif debug file = filepipetask1filepipetask2
It gets messy with wrappers:
file = gulpsrcsrcif debug file = filepipewrapperbeginfilepipetask2if debug file = filepipewrapperend
Instead, try this:
tasksrcdstthentask1ifdebug tasksrcdstthentask2withwrapperifdebug
API
See last section for most of the APIs
- Better API docs
Require Helper
Create through tasks or wrappers with vanilla gulp plugins:
heap = require 'gulp-heap'coffee = heaprequire'gulp-coffee'sourcemaps = heaprequire'gulp-sourcemaps'asWrapper'init''write' # Initiate a task coffeesrcdstopts # As a through task otherTasksrcdst thencoffeeopts # src, dst are omitted withsourcemaps
Convertor
Some gulp plugin modules like gulp-csslint
exports in multiple fields and cannot be required directly. They can be converted by:
heap = require 'gulp-heap'# Require directly csslint = require'gulp-csslint'# Then convert lint = heapconvertcsslinttoTaskreporter = heapconvertcsslintreportertoTask
Current limitations:
- The plugin should only take one arguments
Recipes
Browserify
Direct translation from Gulp Recipes | Browserify + Transforms:
source = heaprequire'vinyl-source-stream'buffer = heaprequire'vinyl-buffer'uglify = heaprequire'gulp-uglify'browserify = heapconvert require'browserify'optsbundletoTask gulptask 'browser' browserifybrowserifyOpts thensource'app.js' thenbufferdestdist nextuglify rename'app.min.js' writedist