{"id":16997,"library":"ember-cli-preprocess-registry","title":"Ember CLI Preprocessor Registry","description":"Ember CLI Preprocessor Registry (npm: `ember-cli-preprocess-registry`) is an internal utility package within the Ember CLI ecosystem, providing a centralized registry for managing various preprocessors for `css`, `template`, and `js` assets. It is currently at version 5.0.1 and primarily maintained as needed for Ember CLI development, without a strict independent release cadence. Its key differentiator is its deep integration into Ember CLI's build pipeline, offering a standard way for addons to register and interact with asset transformations via hooks like `setupPreprocessorRegistry`. This package is not typically consumed directly by end-user applications but is a core component for Ember CLI addons wishing to extend asset compilation.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/ember-cli/ember-cli-preprocessor-registry","tags":["javascript"],"install":[{"cmd":"npm install ember-cli-preprocess-registry","lang":"bash","label":"npm"},{"cmd":"yarn add ember-cli-preprocess-registry","lang":"bash","label":"yarn"},{"cmd":"pnpm add ember-cli-preprocess-registry","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package's primary export is the `Registry` class via CommonJS default export. While internals are ES6ified, direct consumption as ESM may require bundler/transpiler support as there's no explicit `exports` map for ESM in `package.json` v5.x.","wrong":"import { Registry } from 'ember-cli-preprocess-registry';","symbol":"Registry","correct":"const Registry = require('ember-cli-preprocess-registry');"},{"note":"For consumers in an ESM context, a default import usually works with CommonJS default exports, often facilitated by bundlers. However, most addon interactions occur via the `registry` object provided by Ember CLI's `setupPreprocessorRegistry` hook, not by directly importing this class.","wrong":"const { Registry } = require('ember-cli-preprocess-registry');","symbol":"Registry","correct":"import Registry from 'ember-cli-preprocess-registry';"},{"note":"Most Ember CLI addons interact with this package indirectly by receiving an instance of `Registry` (named `registry`) via the `setupPreprocessorRegistry` hook, rather than importing the `Registry` class directly. This is the primary pattern for extending Ember CLI's build process.","wrong":"import { registry } from 'ember-cli-preprocess-registry'; // Incorrect way to obtain the registry instance for addon usage","symbol":"registry (parameter)","correct":"module.exports = {\n  name: 'my-addon',\n  setupPreprocessorRegistry(type, registry) {\n    if (type === 'parent') {\n      registry.add('js', {\n        name: 'my-js-preprocessor',\n        toTree(tree) { return tree; }\n      });\n    }\n  }\n};"}],"quickstart":{"code":"module.exports = {\n  name: 'special-js-sauce',\n  \n  setupPreprocessorRegistry(type, registry) {\n    if (type !== 'parent') { return; }\n\n    registry.add('js', {\n      name: 'special-js-sauce-preprocessor',\n      toTree(tree) {\n        console.log('Processing JavaScript tree with special-js-sauce-preprocessor');\n        // In a real scenario, 'tree' would be a Broccoli node and processing\n        // would return a new Broccoli node. For demonstration, we return it as is.\n        return tree;\n      }\n    });\n    \n    console.log('Registered special-js-sauce-preprocessor for type \"js\"');\n    const jsPlugins = registry.load('js');\n    console.log(`Current JS plugins: ${jsPlugins.map(p => p.name).join(', ')}`);\n  }\n};\n","lang":"javascript","description":"Demonstrates how an Ember CLI addon uses the `setupPreprocessorRegistry` hook to add a custom JavaScript preprocessor to the build pipeline."},"warnings":[{"fix":"Upgrade your Node.js installation to version 16 or 18+.","message":"Version 5.0.0 dropped support for Node.js versions older than 16. Ensure your Node.js environment meets the '16.* || >= 18' requirement.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Refactor template preprocessors to use modern Ember CLI plugin patterns. Legacy template plugins are no longer supported and must be rewritten.","message":"In version 5.0.0, the package was ES6ified, and support for legacy template plugins was entirely removed. Existing code relying on these deprecated template plugin types will break.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure you are using `ember-cli-preprocess-registry@5.0.1` or later if your addon relies on removing plugins by name.","message":"The `registry.remove()` method was broken in version 5.0.0, failing to remove plugins by name. This functionality was restored in v5.0.1. Addons relying on dynamically removing plugins by name would have experienced issues in v5.0.0.","severity":"breaking","affected_versions":"=5.0.0"},{"fix":"Ensure your preprocessor plugin object includes a `name` property (getter) and a `toTree` method that accepts a Broccoli tree and returns a new/modified tree.","message":"Plugins added to the registry must implement a `name` getter and a `toTree(tree)` method (for Broccoli-compatible plugins). Failing to provide these can lead to runtime errors within the Ember CLI build.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 16 or 18 and above. For example, use `nvm install 18 && nvm use 18`.","cause":"Running an Ember CLI project with `ember-cli-preprocess-registry` version 5.x on an unsupported Node.js version (e.g., Node.js < 16).","error":"Error: Node.js v14.x is not supported by ember-cli-preprocess-registry@5.x"},{"fix":"Verify that your `setupPreprocessorRegistry` hook correctly receives the `registry` argument and that any conditional logic for `type` allows the `registry` object to be used when appropriate (e.g., `if (type === 'parent')`).","cause":"Attempting to call `registry.add` or other methods on an undefined `registry` object, often due to an incorrect `type` check or a misconfigured addon.","error":"TypeError: Cannot read properties of undefined (reading 'add') at setupPreprocessorRegistry"},{"fix":"Add a `name` getter to your plugin object, e.g., `get name() { return 'my-plugin'; }`.","cause":"A custom preprocessor plugin object passed to `registry.add` is missing the required `name` property.","error":"Preprocessor plugin 'my-plugin' must define a `name` property."}],"ecosystem":"npm","meta_description":null}