Write your own recipe
A Wheelie recipe is just a collection of Gulp
tasks. Even if you may achieve this work using just Gulp#task()
method, Wheelie exposes a common interface for tasks definition and configurations. In this way, you can
create a collection of common tasks usable among your projects.
The goal of this project is to create a kind of registry for Gulp
so that you can write your frontend toolchain
as a npm
package. Anyway, projects may be slightly different and they may require little customizations such as
changing the destination folder for all of your plugins or changing the image optimization level.
Wheelie addresses the problem, providing an easy way to update your tasks configurations.
Task
The building block of a Wheelie recipe is the Task
model that defines a Gulp
task. Common examples
are watch
, sass
or browserify
tasks.
To create a new Task
you should create a new file in your root folder such as tasks/assets.js
with
the following content:
// requiring the Task model
var Task = require('wheelie/lib/models/task');
// this function provides a lazy loading for your task configurations;
// in this step you can access to the global options
function config(globals) {
return {
src: globals.src + '/assets/**',
dest: globals.dest + '/assets'
};
}
// this function should return the same callback you usually pass to gulp.task();
// in this step, you can access to a common gulp reference and to the Task configuration
// updated with your eventual overrides
function run(gulp, config) {
return function() {
return gulp.src(config.src)
.pipe(gulp.dest(config.dest));
};
}
// you exports a new Task, named 'assets' with the 'image' task as a dependency;
// in this case, 'image' task is launched first
module.exports = new Task('assets', ['image'], run, config);
Task watchers
When you're defining a Task
as you did above, you can set a special attribute to the config
object, so that Wheelie can create automatically a watcher. This makes easy to create your recipe
because you don't need to define a watch
task nor to create a complex way to re-watch changes.
To add a watcher, define the config()
callback as follows:
function config(globals) {
// assuming src and watcher are the same
var source = globals.src + '/assets/**';
return {
watcher: source,
src: source,
dest: globals.dest + '/assets'
};
}
If the attribute watcher
is missing, no watchers are added into the gulp
instance.
The recipe
To put everything together, you should create the tasks/recipe.js
file
as your recipe container:
// assuming you have created the following tasks
var browserify = require('./browserify');
var sass = require('./sass');
var assets = require('./assets');
var templates = require('./templates');
var build = require('./build');
// a recipe is just a list of tasks
module.exports = [browserify, sass, assets, templates, build];
NOTE: if you're going to use Wheelie auto-watchers, the recipe SHOULD expose
a build
task that does all the things.
Add the recipe
To add the recipe above in Wheelie registry, simply:
// import wheelie and your recipe
var Wheelie = require('wheelie');
var recipe = require('./tasks/recipe');
// add the recipe
var wheelie = new Wheelie();
wheelie.add(recipe);
wheelie.build()
Using this configuration, you can launch these Gulp
commands:
$ gulp # launches the setDefault argument
$ gulp build # launches the build TaskGroup
$ gulp sass # launches the sass Task
$ gulp <whatever> # ... and so on ...
Reusing the recipe
To simply re-use a recipe, publish a Wheelie recipe into npm, so that you can install your recipe and
wheelie
packages as devDependencies
in your package.json
. Your frontend toolchain is now under
version control and you can quickly update your projects workflows after each improvement of the toolchain.
Updating tasks options
Some projects may require different tasks configurations, despite what you've planned while writing your recipe.
For this reason, Wheelie exposes an update
method that replaces a task configuration key with the one you've
provided. In this case you can just:
// gulpfile.js
// ...
// update 'sass' configurations, changing 'sourceComments' value to 'map'
wheelie.update('sass', { sourceComments: 'map' });
// but don't update your tasks after this point
// because it's too late
wheelie.build();
During the Wheelie#build()
process, Task#config()
is called and the returned object is patched with your
updates. At this point, the resulting config is passed to Task#run()
method, together with the common gulp
instance.