Broccoli Node Information Utility

2.2.0 · active · verified Sun Apr 19

broccoli-node-info is a low-level JavaScript utility package designed to interact with Broccoli.js plugin instances (nodes). Its primary function is to provide a thin, normalized wrapper around the `node.__broccoliGetInfo__()` internal API, abstracting away differences between various Broccoli node API versions to consistently return a `nodeInfo` object conforming to the latest specification. This package is primarily leveraged by the core Broccoli `Builder` class but is also invaluable for developers performing node inspection, testing, diagnostics, or creating wrappers, offering a safer alternative to directly accessing private node variables like `_name` or `_inputNodes`. The current stable version is 2.2.0, with recent updates like 2.0.0 and 2.1.0 indicating active maintenance and compatibility updates, such as tracking input changes and support for the `volatile` option. Its release cadence aligns with major Broccoli.js ecosystem updates, ensuring it remains a foundational piece for interacting with Broccoli nodes programmatically.

Common errors

```
broccoliNodeInfo.InvalidNodeError: Invalid node: [object String]
```
cause The `getNodeInfo` function was invoked with a plain string instead of a valid Broccoli plugin instance. Plain string nodes are deprecated.

fix If the string represents a source directory, use `broccoli-source` to create a proper source node. Otherwise, ensure the argument is a valid Broccoli plugin instance.
```
broccoliNodeInfo.InvalidNodeError: Invalid node: [object Object]
```
cause The `getNodeInfo` function was called with an object that is not a recognized Broccoli node, or it is a node using the deprecated `.read/.rebuild` API.

fix Verify that the object passed to `getNodeInfo` is an instance of a Broccoli plugin that conforms to the current node API specification. For legacy nodes, consider updating them to the latest API.

Warnings

breaking Version 2.0.0 of `broccoli-node-info` raised the minimum required Node.js version to `8.* || >= 10.*`. Projects running on older Node.js versions (e.g., Node.js 6) will experience failures.
Fix: Upgrade your Node.js environment to version 8 or higher to ensure compatibility with `broccoli-node-info` v2 and above.
deprecated Calling `getNodeInfo()` with plain string nodes (e.g., `'app'`) or nodes conforming to the legacy `.read/.rebuild` API (from Broccoli 1.0 and earlier) will now throw an `InvalidNodeError`. These node types are considered deprecated in the modern Broccoli ecosystem.
Fix: For source directories, use `broccoli-source` instances instead of plain strings. Ensure any custom Broccoli plugins adhere to the latest Broccoli node API specification.
gotcha Directly calling `node.__broccoliGetInfo__()` or accessing private properties like `node._name` or `node._inputNodes` on Broccoli plugin instances is strongly discouraged. These internal APIs are subject to change and may lead to unstable or incorrect behavior across different Broccoli versions.
Fix: Always use `broccoli-node-info.getNodeInfo(node)` to safely inspect Broccoli nodes and retrieve their information in a future-proof manner.

Install

npm install broccoli-node-info npm
yarn add broccoli-node-info yarn
pnpm add broccoli-node-info pnpm

Imports

getNodeInfo
wrong:
```
const broccoliNodeInfo = require('broccoli-node-info');
broccoliNodeInfo.getNodeInfo(node);
```
correct:
```
import { getNodeInfo } from 'broccoli-node-info';
```
Main function to retrieve normalized info for a Broccoli node. The README shows CJS 'require', but ESM imports are preferred for modern Node.js applications.

InvalidNodeError

wrong:

const { InvalidNodeError } = require('broccoli-node-info');

correct:

import { InvalidNodeError } from 'broccoli-node-info';

Custom Error class thrown by `getNodeInfo` when an invalid Broccoli node is passed.

features
wrong:
```
const { features } = require('broccoli-node-info');
```
correct:
```
import { features } from 'broccoli-node-info';
```
A hash representing the supported feature flags for the current node API version, used internally by `getNodeInfo`.

Quickstart

Demonstrates how to use `getNodeInfo` to safely extract information from a Broccoli plugin instance, including handling potential `InvalidNodeError`.

import { getNodeInfo } from 'broccoli-node-info';
import BroccoliPlugin from 'broccoli-plugin';

class MyBroccoliPlugin extends BroccoliPlugin {
  constructor(inputNodes, options) {
    super(inputNodes, {
      annotation: options?.annotation || 'MyBroccoliPlugin',
      name: options?.name || 'MyBroccoliPlugin',
      persistentOutput: true,
      ...options
    });
  }

  async build() {
    // Simulate some build process
    console.log(`Building with ${this.inputNodes.length} input nodes.`);
  }
}

const dummyNode = new MyBroccoliPlugin([], { annotation: 'my-plugin-instance' });

try {
  const nodeInfo = getNodeInfo(dummyNode);
  console.log('Node Name:', nodeInfo.name);
  console.log('Node Annotation:', nodeInfo.annotation);
  console.log('Persistent Output:', nodeInfo.persistentOutput);
  console.log('Input Nodes (raw):', nodeInfo.inputNodes);
} catch (error) {
  console.error('Error getting node info:', error.message);
}

// Example of an invalid node
const invalidNode = 'path/to/my/files'; // Plain string node (deprecated)
try {
  getNodeInfo(invalidNode);
} catch (error) {
  console.error('Caught expected error for invalid node:', error.message);
}

view raw JSON →