Base class for all Broccoli plugins
npm install broccoli-plugin

``js
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 = this.input.readFileSync(foo.txt);
const output = someCompiler(input);
// Write to 'bar.txt' in this node's output
this.output.writeFileSync(bar.txt, output);`
}
}
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 this.constructor.name.annotation
- : A descriptive annotation. Useful for debugging, to tellpersistentOutput
multiple instances of the same plugin apart.
- : If true, the output directory is not automaticallyneedsCache
emptied between builds.
- : If true, a cache directory is created automaticallycachePath
and the path is set at . If false, a cache directory is not createdthis.cachePath
and is undefined. Defaults to true.volatile
- : If true, memoization will not be applied and the build method willfalse
always be called regardless if the inputNodes have changed. Defaults to .trackInputChanges
- : If true, a change object will be passed to the build method which containsfalse
information about which input has changed since the last build. Defaults to .
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 ininputNodes
. Your plugin will read files from these paths.
- this.outputPath: The path on disk corresponding to this plugin instancepersistentOutput
(this node). Your plugin will write files to this path. This directory is
emptied by Broccoli before each build, unless the options
is true.
- this.cachePath: The path on disk to an auxiliary cache directory. Use thisneedsCache
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
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.
If the trackInputChanges option was set to true, an object will be passed to the
build method with the shape of:
`js`
{
changedNodes: [true, true, ...]
}
This array contain a booleans corresponding to each input node as to whether or not that node changed since the last rebuild. For the initial build all values in the array will be true.
Advanced usage only.
Return the object on which Broccoli will call obj.build(). Called once afterthis
instantiation. By default, returns . 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 mightreturn { build: this.buildWrapper.bind(this) }.return new MyPluginWorker(this.inputPaths, this.outputPath, this.cachePath)
Or, to hand off the plugin implementation to a completely separate object:,MyPluginWorker
where provides a .build method.
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 theinputPaths
directoriestreeDir
- : The path that file is relative to. Must be an element ofthis.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)
An api which enables a plugin to easily read from one or more input directories ergonomically and safely.
_Note: We recommend users stop using this.inputPaths and instead rely on this.input. Our plan at present is to strongly consider deprecation of this.inputPaths once this.input has had time to bake._
this.input's features:
- this.input reads from the provided inputPaths. No path concatenation required.this.input
- provides readOnly file system APIs. This prevents a plugin from erroneously mutating its inputs.this.input
- provides a merged view of inputs, this allows every plugin to easily support multiple inputs, without the use of broccoli-merge-trees or implementing a complex merge algorithm.this.input.at(index)
- provides access to each individual input if desired.
Example:
`js
// old
fs.readFileSync(this.inputPaths[0] + '/file.txt');
// new (merged): Most Common
this.input.readFileSync('file.txt');
// new (indexed): For when you need to disambiguate between inputs.
this.input.at(0).readFileSync('file.txt);
// ReadOnly
this.input.writeFileSync // throws error
`
- readFileSync
- existsSync
- lstatSync
- statSync
- readdirSync
- at
Read more about input here
Note: input will be available only after the build starts.
An api which enables a plugin to easily write to the output directory ergonomically and safely.
_Note: We recommend users stop using this.outputPath and instead rely on this.output. Our plan at present is to strongly consider deprecation of this.outputPath once this.output has had time to bake._
this.output's features:
- this.ouput writes to the outputPath. No path concatenation required.this.output
- provides read operations on the outputPath. No path concatenation required.
Ex:
`js
// old
fs.writeFileSync(this.outputPath + '/file.txt', 'text');
// new
this.output.writeFileSync('file.txt', 'text');
`
- readFileSync
- existsSync
- lstatSync
- readdirSync
- statSync
- writeFileSync
- appendFileSync
- rmdirSync
- mkdirSync
Read more about APIs present in output here.
Note: output will be available only after the build` starts.