- Ember.js v4.12 or above
- Ember CLI v4.12 or above
@embroider/compat3.4.3 or above (optional)- Node.js v20 or above
You can add custom plugins to be used during transpilation of the addon/ or
addon-test-support/ trees of your addon (or the app/ and tests/ trees of an application)
by registering a custom AST transform.
var SomeTransform = require('./some-path/transform'); module.exports = { name: 'my-addon-name', included: function() { // we have to wrap these in an object so the ember-cli // registry doesn't try to call `new` on them (new is actually // called within htmlbars when compiling a given template). this.app.registry.add('htmlbars-ast-plugin', { name: 'some-transform', plugin: SomeTransform }); this._super.included.apply(this, arguments); } };
name- String. The name of the AST transform for debugging purposes.plugin- A function of typeASTPluginBuilder.dependencyInvalidation- Boolean. A flag that indicates the AST Plugin may, on a per-template basis, depend on other files that affect its output.cacheKey- function that returns any JSON-compatible value - The value returned is used to invalidate the persistent cache across restarts, usually in the case of a dependency or configuration change.baseDir-() => string. A function that returns the directory on disk of the npm module for the plugin. If provided, a basic cache invalidation is performed if any of the dependencies change (e.g. due to a npm install/upgrade).
Plugins that set the dependencyInvalidation option to true can provide function for the plugin of type ASTDependencyPlugin as given below.
Note: the plugin function is invoked without a value for this in context.
import {ASTPluginBuilder, ASTPlugin} from "@glimmer/syntax/dist/types/lib/parser/tokenizer-event-handlers"; export type ASTDependencyPlugin = ASTPluginWithDepsBuilder | ASTPluginBuilderWithDeps; export interface ASTPluginWithDepsBuilder { (env: ASTPluginEnvironment): ASTPluginWithDeps; } export interface ASTPluginBuilderWithDeps extends ASTPluginBuilder { /** * @see {ASTPluginWithDeps.dependencies} below. **/ dependencies(relativePath): string[]; } export interface ASTPluginWithDeps extends ASTPlugin { /** * If this method exists, it is called with the relative path to the current * file just before processing starts. Use this method to reset the * dependency tracking state associated with the file. */ resetDependencies?(relativePath: string): void; /** * This method is called just as the template finishes being processed. * * @param relativePath {string} A relative path to the file that may have dependencies. * @return {string[]} paths to files that are a dependency for the given * file. Any relative paths returned by this method are taken to be relative * to the file that was processed. */ dependencies(relativePath: string): string[]; }
You can still provide a custom path to the template compiler (e.g. to test custom template compiler tweaks in an application) by:
// ember-cli-build.js module.exports = function(defaults) { let app = new EmberApp(defaults, { 'ember-cli-htmlbars': { templateCompilerPath: `some_path/to/ember-template-compiler.js`, } }); };
var HtmlbarsCompiler = require('ember-cli-htmlbars'); var templateTree = new HtmlbarsCompiler('app/templates', { isHTMLBars: true, // provide the templateCompiler that is paired with your Ember version templateCompiler: require('./bower_components/ember/ember-template-compiler') });