The Broccoli Plugin Base Class
Example Usage
const Plugin = require('broccoli-plugin');
class MyPlugin extends Plugin {
constructor(inputNodes, options = {}) {
super(inputNodes, {
annotation: options.annotation
});
}
build() {
const input = fs.readFileSync(`${this.inputPaths[2]}/foo.txt`);
const output = someCompiler(input);
fs.writeFileSync(`${this.outputPath}/bar.txt`, output);
}
};
Reference
new Plugin(inputNodes, options)
Call this base class constructor from your subclass constructor.
Plugin.prototype.build()
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.
Plugin.prototype.getCallbackObject()
Advanced usage only.
Return the object on which Broccoli will call obj.build()
. 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
directoriestreeDir
: 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)