Broccoli

Note April 7, 2014: There was a recent data loss issue on OS X in Broccoli and several plugins. Check to see if you're affected.

A fast, reliable asset pipeline, supporting constant-time rebuilds and compact build definitions. Comparable to the Rails asset pipeline in scope, though it runs on Node and is backend-agnostic. For background and architecture, see the introductory blog post.

For the command line interface, see broccoli-cli.

This is 0.x beta software.

Windows is not yet supported.

Installation

npm install --save-dev broccoli
npm install --global broccoli-cli

Getting Started

Check out broccoli-sample-app.

Brocfile.js

A Brocfile.js file in the project root contains the build specification. It should export a tree which may simply be the directory path (as a string). To build more advanced output trees you may want to use some of the plugins listed below.

The following would export the app/ subdirectory as a tree:

module.exports = 'app'

Alternatively, the following would export the app/ subdirectory as appkit/:

var pickFiles = require('broccoli-static-compiler')

module.exports = pickFiles('app', {
  srcDir: '/',
  destDir: 'appkit'
})

Plugins

• broccoli-autoprefixer
• broccoli-bake-handlebars
• broccoli-bower
• broccoli-closure-compiler
• broccoli-coffee
• broccoli-csso
• broccoli-defeatureify
• broccoli-dust
• broccoli-ember-script
• broccoli-es6-concatenator
• broccoli-es6-module-filter
• broccoli-es6-transpiler
• broccoli-file-creator
• broccoli-file-mover
• broccoli-file-remover
• broccoli-fixturify
• broccoli-htmlmin
• broccoli-jade
• broccoli-nunjucks
• broccoli-regenerator
• broccoli-replace
• broccoli-sass
• broccoli-static-compiler
• broccoli-strip-debug
• broccoli-strip-json-comments
• broccoli-svgo
• broccoli-sweetjs
• broccoli-swig
• broccoli-template
• broccoli-traceur
• broccoli-uglify-js
• broccoli-uncss

More plugins may be found under the broccoli-plugin keyword on npm.

Plugging Broccoli Into Other Tools

• grunt-broccoli
• grunt-broccoli-build

Helpers

Shared code for writing plugins.

• broccoli-env
• broccoli-filter
• broccoli-writer
• node-quick-temp

Plugin API Specification

Broccoli defines a single plugin API: a tree. A tree object represents a tree (directory hierarchy) of files that can be regenerated on each build.

By convention, plugins will export a function that takes one or more input trees, and returns an output tree object.

A tree object must supply two methods that will be called by Broccoli:

tree.read(readTree)

The .read method must return a path or a promise for a path, containing the tree contents.

It receives a readTree function argument from Broccoli. If .read needs to read other trees, it must not call otherTree.read directly. Instead, it must call readTree(otherTree), which returns a promise for the path containing otherTree's contents. It must not call readTree again until the promise has resolved; that is, it cannot call readTree on multiple trees in parallel.

Broccoli will call the .read method repeatedly to rebuild the tree, but at most once per rebuild; that is, if a tree is used multiple times in a build definition, Broccoli will reuse the path returned instead of calling .read again.

The .read method is responsible for creating a new temporary directory to store the tree contents in. Subsequent invocations of .read should remove temporary directories created in previous invocations.

tree.cleanup()

For every tree whose .read method was called one or more times, the .cleanup method will be called exactly once. No further .read calls will follow .cleanup. The .cleanup method should remove all temporary directories created by .read.

Security

• Do not run broccoli serve on a production server. While this is theoretically safe, it exposes a needlessly large amount of attack surface just for serving static assets. Instead, use broccoli build to precompile your assets, and serve the static files from a web server of your choice.

Get Help

• IRC: #broccolijs on Freenode
• Twitter: mention @jo_liss with your question
• GitHub: Open an issue on a specific plugin repository, or on this repository for general questions.

License

Broccoli was originally written by Jo Liss and is licensed under the MIT license.