{"id":12906,"library":"broccoli-node-api","title":"Broccoli Node API Types","description":"`broccoli-node-api` is a TypeScript package that provides canonical type definitions for the Broccoli Node API. It is an essential component for developers creating custom plugins (nodes) for the Broccoli build system, ensuring type safety and enhancing the developer experience within the Broccoli ecosystem. As of version 1.7.0, this library comprehensively covers types for core concepts like `Node`, `InputNode`, `TransformNode`, and `SourceNode`, along with their associated information objects such as `TransformNodeInfo` and `SourceNodeInfo`, and callback interfaces like `CallbackObject` and `BuildChangeObject`. The package directly mirrors the specification outlined in the official Broccoli Node API documentation, facilitating the correct implementation of build hooks and data structures. Its release cadence is tightly coupled with the evolution of the Broccoli core, aiming to always provide up-to-date type definitions. Its primary differentiator is its role as the official, direct, and canonical source of truth for plugin typings within the Broccoli build system.","status":"active","version":"1.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/broccolijs/broccoli-node-api","tags":["javascript","typescript"],"install":[{"cmd":"npm install broccoli-node-api","lang":"bash","label":"npm"},{"cmd":"yarn add broccoli-node-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add broccoli-node-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Import as a type, not a runtime value, as this package only provides type definitions.","wrong":"import { Node } from 'broccoli-node-api';","symbol":"Node","correct":"import type { Node } from 'broccoli-node-api';"},{"note":"Used for defining the structure of a Broccoli transform plugin's info object. Always use type imports.","wrong":"const { TransformNodeInfo } = require('broccoli-node-api');","symbol":"TransformNodeInfo","correct":"import type { TransformNodeInfo } from 'broccoli-node-api';"},{"note":"Defines the `build` method for Broccoli nodes. It's a named type export.","wrong":"import CallbackObject from 'broccoli-node-api';","symbol":"CallbackObject","correct":"import type { CallbackObject } from 'broccoli-node-api';"}],"quickstart":{"code":"import type { TransformNodeInfo, FeatureSet, BuildChangeObject, Node } from 'broccoli-node-api';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\n\ninterface MyTransformNodeOptions {\n  annotation?: string;\n}\n\nclass MyExampleTransformNode {\n  private annotation: string | null | undefined;\n  private inputNodes: Node[];\n\n  constructor(inputNodes: Node[], options?: MyTransformNodeOptions) {\n    this.inputNodes = inputNodes;\n    this.annotation = options?.annotation;\n  }\n\n  __broccoliGetInfo__(builderFeatures: FeatureSet): TransformNodeInfo {\n    const nodeInfo: TransformNodeInfo = {\n      nodeType: 'transform',\n      name: 'MyExampleTransform',\n      annotation: this.annotation,\n      instantiationStack: new Error().stack!,\n      inputNodes: this.inputNodes,\n      persistentOutput: false,\n      needsCache: true,\n      volatile: false,\n      trackInputChanges: false,\n      setup(features: FeatureSet, options: { inputPaths: string[]; outputPath: string; cachePath: string }): void {\n        // Perform any setup necessary, e.g., create directories\n        // console.log('Setup called with:', options);\n      },\n      getCallbackObject(): CallbackObject {\n        return {\n          async build(buildChangeObject?: BuildChangeObject): Promise<void> {\n            const { inputPaths, outputPath } = (this as any).__$broccoliGetInfo__()._options;\n            const [inputPath] = inputPaths;\n            \n            // Example: Copy files from input to output\n            const files = await fs.readdir(inputPath);\n            for (const file of files) {\n              const source = path.join(inputPath, file);\n              const destination = path.join(outputPath, file);\n              await fs.copyFile(source, destination);\n            }\n            console.log(`Copied ${files.length} files from ${inputPath} to ${outputPath}`);\n          },\n        };\n      },\n    };\n    return nodeInfo;\n  }\n}\n\n// Example usage (typically in a Brocfile.ts):\n// Assume 'myInputTree' is another Broccoli Node or a string path\n// const myInputTree = 'app';\n// const myTransform = new MyExampleTransformNode([myInputTree], { annotation: 'My Custom Transform' });\n// export default myTransform;\n\nconsole.log('MyExampleTransformNode class defined, ready for Broccoli usage.');\n","lang":"typescript","description":"Demonstrates how to implement a basic Broccoli `TransformNode` using the provided TypeScript types, including the `__broccoliGetInfo__` method and the `build` callback."},"warnings":[{"fix":"Consult the Broccoli documentation and the `broccoli-node-api` changelog for specific API changes. Update your Broccoli plugins to conform to the new interface specifications, particularly how `__broccoliGetInfo__` and the `CallbackObject` methods are implemented.","message":"Major version updates of `broccoli-node-api` typically signal corresponding breaking changes in the underlying Broccoli Node API itself. While this package provides types, changes in the core API will necessitate updates to your Broccoli plugins and potentially your `Brocfile.ts`. Always review the Broccoli core changelog and this package's release notes when upgrading across major versions. For instance, Broccoli v2.0 deprecating the `.read` and `.rebuild` APIs required plugins to adapt to the `__broccoliGetInfo__` interface.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure all imports from `broccoli-node-api` use the `import type` syntax: `import type { SymbolName } from 'broccoli-node-api';`. These types are stripped out during compilation and have no runtime presence.","message":"This package exports *only* TypeScript type definitions. Attempting to import these types as runtime values using `require()` or standard ES module imports (e.g., `import { Node } from '...'`) will lead to runtime errors (e.g., `TypeError: ... is not a function` or `undefined`). Always use `import type { ... } from 'broccoli-node-api';` to explicitly import only the types.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `instantiationStack` primarily for debugging and diagnostic reporting. Avoid parsing or making critical application logic decisions based on its precise string content. If specific stack information is needed, consider implementing custom stack capturing mechanisms.","message":"Relying on the exact format or contents of the `instantiationStack` property (available on `NodeInfoCommon` and its derivatives) for production logic is strongly discouraged. While exposed for debugging purposes within the Broccoli core, its internal structure and verbosity can vary across Broccoli versions and environments without explicit API changes.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add an explicit type import statement: `import type { TransformNode } from 'broccoli-node-api';`","cause":"The TypeScript compiler cannot find the `TransformNode` type because it was not correctly imported.","error":"Cannot find name 'TransformNode'. Did you mean 'TransformStream'?"},{"fix":"Change the import statement to `import type { TransformNode } from 'broccoli-node-api';`. `TransformNode` is a type definition, not a runtime construct.","cause":"Attempting to use a type (`TransformNode`) as if it were a callable function, class, or runtime value. This happens when `import { TransformNode } from '...'` is used instead of `import type { TransformNode } from '...'`, and the compiled JavaScript tries to access it.","error":"TypeError: (0 , broccoli_node_api_1.TransformNode) is not a function"},{"fix":"Ensure your Broccoli plugin fully implements all the properties and methods required by the specific `NodeInfo` interface (e.g., `TransformNodeInfo`, `SourceNodeInfo`), as detailed in the Broccoli Node API documentation. The TypeScript error indicates exactly which property is missing.","cause":"Your Broccoli plugin object, which is typed as `TransformNode` or similar, is missing a required property or method (e.g., `setup`, `getCallbackObject`, `inputNodes`, `build`) as defined by the `TransformNodeInfo` or `SourceNodeInfo` interface.","error":"Property 'setup' is missing in type 'MyNode' but required in type 'TransformNodeInfo'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}