broccoli-plugin

What is broccoli-plugin?

The broccoli-plugin npm package is a base class for Broccoli plugins. Broccoli is a JavaScript build tool, and this package allows developers to create custom plugins for their build pipelines. It provides a structured way to define input and output nodes, manage file transformations, and handle build errors.

What are broccoli-plugin's main functionalities?

Creating a Basic Plugin

This code demonstrates how to create a basic Broccoli plugin that reads a file, transforms its content to uppercase, and writes the result to the output directory.

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

class MyPlugin extends Plugin {
  constructor(inputNodes, options) {
    super(inputNodes, options);
  }

  build() {
    const inputPath = this.inputPaths[0];
    const outputPath = this.outputPath;
    const inputFile = `${inputPath}/input.txt`;
    const outputFile = `${outputPath}/output.txt`;

    const content = fs.readFileSync(inputFile, 'utf8');
    const transformedContent = content.toUpperCase();
    fs.writeFileSync(outputFile, transformedContent);
  }
}

module.exports = MyPlugin;

Handling Multiple Input Nodes

This example shows how to handle multiple input nodes in a Broccoli plugin. It reads files from two different input directories, combines their contents, and writes the result to the output directory.

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

class MultiInputPlugin extends Plugin {
  constructor(inputNodes, options) {
    super(inputNodes, options);
  }

  build() {
    const inputPath1 = this.inputPaths[0];
    const inputPath2 = this.inputPaths[1];
    const outputPath = this.outputPath;

    const content1 = fs.readFileSync(`${inputPath1}/file1.txt`, 'utf8');
    const content2 = fs.readFileSync(`${inputPath2}/file2.txt`, 'utf8');
    const combinedContent = content1 + '\n' + content2;

    fs.writeFileSync(`${outputPath}/combined.txt`, combinedContent);
  }
}

module.exports = MultiInputPlugin;

Error Handling in Plugins

This code demonstrates how to handle errors in a Broccoli plugin. It checks if the input file exists and throws an error if it does not. Any errors encountered during the build process are caught and logged.

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

class ErrorHandlingPlugin extends Plugin {
  constructor(inputNodes, options) {
    super(inputNodes, options);
  }

  build() {
    try {
      const inputPath = this.inputPaths[0];
      const outputPath = this.outputPath;
      const inputFile = `${inputPath}/input.txt`;
      const outputFile = `${outputPath}/output.txt`;

      if (!fs.existsSync(inputFile)) {
        throw new Error('Input file does not exist');
      }

      const content = fs.readFileSync(inputFile, 'utf8');
      const transformedContent = content.toUpperCase();
      fs.writeFileSync(outputFile, transformedContent);
    } catch (error) {
      console.error('Build error:', error);
    }
  }
}

module.exports = ErrorHandlingPlugin;

Other packages similar to broccoli-plugin

gulp

Gulp is a toolkit for automating painful or time-consuming tasks in your development workflow. It uses a code-over-configuration approach and streams to handle file transformations. Compared to Broccoli, Gulp is more flexible and has a larger ecosystem of plugins, but it can be more complex to set up and use.

webpack

Webpack is a module bundler that takes modules with dependencies and generates static assets representing those modules. It is highly configurable and supports a wide range of plugins and loaders. Webpack is more focused on bundling JavaScript applications, whereas Broccoli is more general-purpose for file transformations.

rollup

Rollup is a module bundler for JavaScript that compiles small pieces of code into something larger and more complex, such as a library or application. It is known for its tree-shaking capabilities, which help to remove unused code. Rollup is more specialized for JavaScript bundling, while Broccoli is a more general build tool.

README

The Broccoli Plugin Base Class

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 = this.input.readFileSync(`foo.txt`);
    const output = someCompiler(input);

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

Reference

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 this.constructor.name.
  • 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.
  • volatile : If true, memoization will not be applied and the build method will always be called regardless if the inputNodes have changed. Defaults to false.
  • trackInputChanges : If true, a change object will be passed to the build method which contains information about which input has changed since the last build. Defaults to false.

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.

If the trackInputChanges option was set to true, an object will be passed to the build method with the shape of:

{
  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.

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 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)

Plugin.prototype.input

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:

// 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

List of Methods

• readFileSync
• existsSync
• lstatSync
• statSync
• readdirSync
• at

Read more about input here

Note: input will be available only after the build starts.

Plugin.prototype.output

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:

// old
fs.writeFileSync(this.outputPath + '/file.txt', 'text');

// new
this.output.writeFileSync('file.txt', 'text');

List of Methods

• 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.

Changelog

v4.0.4 (2021-03-11)

:bug: Bug Fix

• #55 Avoid forcing eager calculation of error stacks (@rwjblue)

:house: Internal

• #56 Add release automation setup (@rwjblue)

Committers: 1

• Robert Jackson (@rwjblue)