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.
npm install --save-dev broccolinpm install --global broccoli-cli
Brocfile.js file in the project root contains the build specification. It
should export a tree.
A tree can be any string representing a directory path, like
'src'. Or a tree can be an object conforming to the Plugin API
Brocfile.js will usually
directly work with only directory paths, and then use the plugins in the
Plugins section to generate transformed trees.
The following simple
Brocfile.js would export the
app/ subdirectory as a
moduleexports = 'app'
With that Brocfile, the build result would equal the contents of the
tree in your project folder. For example, say your project contains these
app ├─ main.js └─ helper.js Brocfile.js package.json …
broccoli build the-output (a command provided by
broccoli-cli) would generate
the following folder within your project folder:
the-output ├─ main.js └─ helper.js
Using plugins in a
Brocfile.js exports the
app/ subdirectory as
var Funnel =moduleexports = 'app'destDir: 'appkit'
That example uses the plugin
In order for the
require call to work, you must first put the plugin in
devDependencies and install it, with
npm install --save-dev broccoli-funnel
With the above
Brocfile.js and the file tree from the previous example,
broccoli build the-output would generate the following folder:
the-output └─ appkit ├─ main.js └─ helper.js
You can find plugins under the broccoli-plugin keyword on npm.
Using Broccoli Programmatically
In addition to using Broccoli via the combination of
broccoli-cli and a
Brocfile.js, you can also use Broccoli programmatically to construct your own build output via the
Builder class. The
Builder is one of the core APIs in Broccoli, and is responsible for taking a graph of Broccoli nodes and producing an actual build artifact (i.e. the output usually found in your
dist directory after you run
broccoli build). The output of a
build method is a Promise that resolves when all the operations in the graph are complete. You can use this promise to chain together additional operations (such as error handling or cleanup) that will execute once the build step is complete.
By way of example, let's assume we have a graph of Broccoli nodes constructed via a combination of
const html = appRootfiles: 'index.html'annotation: 'Index file'const js = appRootfiles: 'app.js'destDir: '/assets'annotation: 'JS Files';const css = appRootsrcDir: 'styles'files: 'app.css'destDir: '/assets'annotation: 'CSS Files';const public = appRootannotation: 'Public Files';const tree = html js css public;
At this point,
tree is a graph of nodes, each of which can represent either an input or a transformation that we want to perform. In other words,
tree is an abstract set of operations, not a concrete set of output files.
In order to perform all the operations described in
tree, we need to do the following:
- construct a
Builderinstance, passing in the graph we constructed before
- call the
buildmethod, which will traverse the graph, performing each operation and eventually writing the output to a temporary folder indicated by
Since we typically want do more than write to a temporary folder, we'll also use a library called
TreeSync to sync the contents of the temp file with our desired output directory. Finally, we'll clean up the temporary folder once all our operations are complete:
const Builder = ;const TreeSync = ;// ...snip...const tree = html js css public;const builder = tree;const outputDir = 'dist';const outputTree = builderoutputPath outputDir;builder;
Running Broccoli, Directly or Through Other Tools
Shared code for writing plugins.
Plugin API Specification
Also see docs/broccoli-1-0-plugin-api.md on how to upgrade from Broccoli 0.x to the Broccoli 1.x API.
- Do not run
broccoli serveon 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 buildto precompile your assets, and serve the static files from a web server of your choice.
#broccolijson Freenode. Ask your question and stick around for a few hours. Someone will see your message eventually.
- Twitter: mention @jo_liss with your question
- GitHub: Open an issue on a specific plugin repository, or on this repository for general questions.