Broccoli is a great tool for building up assets gradually through a list of changing steps. Unfortunately, when things go wrong in one of your steps it is often very difficult to figure out what is happening at each stage.
Here is where broccoli-stew comes in, it is a Broccoli utility library that contains a number of super useful plugins with a posix flair to them. Tools like mv
, rename
, find
, map
, rm
, log
, and debug
make it much easier to reason about your Broccoli build.
And thanks to the debug
and log
plugins it has become massively easier to log the contents of each tree, or get an extra copy to poke at manually.
Initial Brocfile.js
Lets assume you have the following Brocfile.js
:
// Brocfile.js
var Funnel = require('broccoli-funnel');
var ES2015 = require('broccoli-es6modules');
var log = require('broccoli-stew').log;
var app = new Funnel('app', {
destDir: 'my-app-name',
});
var transpiledTree = new ES2015(app);
module.exports = transpiledTree;
The goal of the Brocfile.js listed above is:
- Grab all files in
app/
and its subdirectories - “move” those files to
my-app-name/
- transpile those files from ES2015.
So far this seems pretty easy, but what if your resulting output didn’t contain the files you expected? How would you track that down?
Log Tree
You can log the files in a tree using broccoli-stew
’s log
:
// Brocfile.js
var Funnel = require('broccoli-funnel');
var ES2015 = require('broccoli-es6modules');
var log = require('broccoli-stew').log;
var app = new Funnel('app', {
destDir: 'my-app-name'
});
var loggedApp = log(app, { output: 'tree', label: 'my-app-name tree' });
var transpiledTree = new ES2015(loggedApp);
module.exports = transpiledTree;
Using log
like this will list out the files that are present just after the Funnel
step. It might output something like the following:
my-app-name tree
└── my-app-name/
├── my-app-name/cat.js
└── my-app-name/dog.js
This is super helpful to see that the right files are selected, but what if you are seeing the right files but the contents were not right?
Debug Tree
Using broccoli-stew
’s debug
you can have a duplicate copy of the tree generated into the root of the project so you can inspect it later (it will not get cleaned up at the end of the build like the temp folders do).
// Brocfile.js
var Funnel = require('broccoli-funnel');
var ES2015 = require('broccoli-es6modules');
var debug = require('broccoli-stew').debug;
var app = new Funnel('app', {
destDir: 'my-app-name'
});
var debugApp = debug(app, { name: 'my-app-name' });
var transpiledTree = new ES2015(debugApp);
module.exports = transpiledTree;
The debug
plugin as used above will create a folder on disk at DEBUG-my-app-name
in the root of your project with the full contents of the app
tree when it was called. You can review this folder’s contents at your leisure without worrying about the Broccoli server calling cleanup and deleting the directory.
Conclusion
Using broccoli-stew
to debug a Broccoli pipeline is absolutely awesome, and makes getting a project using Broccoli much easier. Thanks to @stefanpenner and @chadhietala for pushing things forward!
If you’d like to checkout and play with the Brocfile.js
above, you can do the normal git clone
and npm install
song and dance with https://github.com/rwjblue/debugging-broccoli.