Skip to content
Base class for Broccoli plugins
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.eslintignore add eslint, match config of broccoli repo Mar 3, 2019
.gitignore Use multidep for testing against multiple Broccoli versions Oct 15, 2015
.travis.yml Update for 1.3.1. Aug 8, 2018
LICENSE Add initial sketch of plugin base class Apr 24, 2015
index.js add eslint, match config of broccoli repo Mar 3, 2019
prettier.config.js add prettier matching broccoli's config Mar 3, 2019
yarn.lock add eslint, match config of broccoli repo Mar 3, 2019

The Broccoli Plugin Base Class

Build Status Build status

Example Usage

const Plugin = require('broccoli-plugin');

class MyPlugin extends Plugin {

  constructor(inputNodes, options = {}) {
    super(inputNodes, {
      annotation: options.annotation
      // see `options` in the below README to see a full list of constructor options

  build() {
    // Read files from this.inputPaths, and write files to this.outputPath.
    // Silly example:

    // Read 'foo.txt' from the third input node
    const input = fs.readFileSync(`${this.inputPaths[2]}/foo.txt`);
    const output = someCompiler(input);

    // Write to 'bar.txt' in this node's output
    fs.writeFileSync(`${this.outputPath}/bar.txt`, output);


new Plugin(inputNodes, options)

Call this base class constructor from your subclass constructor.

  • inputNodes: An array of node objects that this plugin will read from. Nodes are usually other plugin instances; they were formerly known as "trees".

  • options

    • name: The name of this plugin class. Defaults to
    • annotation: A descriptive annotation. Useful for debugging, to tell multiple instances of the same plugin apart.
    • persistentOutput: If true, the output directory is not automatically emptied between builds.
    • needsCache : If true, a cache directory is created automatically and the path is set at cachePath. If false, a cache directory is not created and this.cachePath is undefined. Defaults to true.

Override this method in your subclass. It will be called on each (re-)build.

This function will typically access the following read-only properties:

  • this.inputPaths: An array of paths on disk corresponding to each node in inputNodes. Your plugin will read files from these paths.

  • this.outputPath: The path on disk corresponding to this plugin instance (this node). Your plugin will write files to this path. This directory is emptied by Broccoli before each build, unless the persistentOutput options is true.

  • this.cachePath: The path on disk to an auxiliary cache directory. Use this to store files that you want preserved between builds. This directory will only be deleted when Broccoli exits. If a cache directory is not needed, set needsCache to false when calling broccoli-plugin constructor.

All paths stay the same between builds.

To perform asynchronous work, return a promise. The promise's eventual value is ignored (typically null).

To report a compile error, throw it or return a rejected promise. Also see section "Error Objects" below.


Advanced usage only.

Return the object on which Broccoli will call Called once after instantiation. By default, returns this. Plugins do not usually need to override this, but it can be useful for base classes that other plugins in turn derive from, such as broccoli-caching-writer.

For example, to intercept .build() calls, you might return { build: this.buildWrapper.bind(this) }. Or, to hand off the plugin implementation to a completely separate object: return new MyPluginWorker(this.inputPaths, this.outputPath, this.cachePath), where MyPluginWorker provides a .build method.

Error Objects

To help with displaying clear error messages for build errors, error objects may have the following optional properties in addition to the standard message property:

  • file: Path of the file in which the error occurred, relative to one of the inputPaths directories
  • treeDir: The path that file is relative to. Must be an element of this.inputPaths. (The name treeDir is for historical reasons.)
  • line: Line in which the error occurred (one-indexed)
  • column: Column in which the error occurred (zero-indexed)
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.