Ember CLI Preprocessor Registry

Common errors

• Error: Node.js v14.x is not supported by ember-cli-preprocess-registry@5.x

  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).
  fix Upgrade your Node.js environment to version 16 or 18 and above. For example, use `nvm install 18 && nvm use 18`.

• TypeError: Cannot read properties of undefined (reading 'add') at setupPreprocessorRegistry

  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.
  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')`).

• Preprocessor plugin 'my-plugin' must define a `name` property.

  cause A custom preprocessor plugin object passed to `registry.add` is missing the required `name` property.
  fix Add a `name` getter to your plugin object, e.g., `get name() { return 'my-plugin'; }`.

Warnings

• breaking Version 5.0.0 dropped support for Node.js versions older than 16. Ensure your Node.js environment meets the '16.* || >= 18' requirement.
  Fix: Upgrade your Node.js installation to version 16 or 18+.
• breaking 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.
  Fix: Refactor template preprocessors to use modern Ember CLI plugin patterns. Legacy template plugins are no longer supported and must be rewritten.
• breaking 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.
  Fix: Ensure you are using `ember-cli-preprocess-registry@5.0.1` or later if your addon relies on removing plugins by name.
• gotcha 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.
  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.

Install

• npm install ember-cli-preprocess-registry npm
• yarn add ember-cli-preprocess-registry yarn
• pnpm add ember-cli-preprocess-registry pnpm

Imports

• Registry
  wrong:

  import { Registry } from 'ember-cli-preprocess-registry';

  correct:

  const Registry = require('ember-cli-preprocess-registry');

  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.
• Registry
  wrong:

  const { Registry } = require('ember-cli-preprocess-registry');

  correct:

  import Registry from 'ember-cli-preprocess-registry';

  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.
• registry (parameter)
  wrong:

  import { registry } from 'ember-cli-preprocess-registry'; // Incorrect way to obtain the registry instance for addon usage

  correct:

  module.exports = {
    name: 'my-addon',
    setupPreprocessorRegistry(type, registry) {
      if (type === 'parent') {
        registry.add('js', {
          name: 'my-js-preprocessor',
          toTree(tree) { return tree; }
        });
      }
    }
  };

  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.

Quickstart

Demonstrates how an Ember CLI addon uses the `setupPreprocessorRegistry` hook to add a custom JavaScript preprocessor to the build pipeline.

module.exports = {
  name: 'special-js-sauce',
  
  setupPreprocessorRegistry(type, registry) {
    if (type !== 'parent') { return; }

    registry.add('js', {
      name: 'special-js-sauce-preprocessor',
      toTree(tree) {
        console.log('Processing JavaScript tree with special-js-sauce-preprocessor');
        // In a real scenario, 'tree' would be a Broccoli node and processing
        // would return a new Broccoli node. For demonstration, we return it as is.
        return tree;
      }
    });
    
    console.log('Registered special-js-sauce-preprocessor for type "js"');
    const jsPlugins = registry.load('js');
    console.log(`Current JS plugins: ${jsPlugins.map(p => p.name).join(', ')}`);
  }
};