Ember CLI HTMLBars

Compatibility

• Ember.js v3.8 or above
• Ember CLI v3.8 or above
• Node.js v12 or above

Tagged Template Usage / Migrating from htmlbars-inline-precompile

Starting with version 4.0, this addon now includes the testing helper from ember-cli-htmlbars-inline-precompile

This will require an update to the imports of the hbs helper in your tests:

Prior syntax:

import hbs from 'htmlbars-inline-precompile';
...
await render(hbs`
<MyComponent />
`);

New syntax:

import { hbs } from 'ember-cli-htmlbars';
...
await render(hbs`
<MyComponent />
`);

There is a codemod available to automate this change.

Additional Trees

For addons which want additional customizations, they are able to interact with this addon directly.

interfaceEmberCLIHTMLBars{/** Supports easier transpilation of non-standard input paths (e.g. to transpile a non-addon NPM dependency) while still leveraging the logic within ember-cli-htmlbars for transpiling (e.g. custom AST transforms, colocation, etc). */transpileTree(inputTree: BroccoliTree): BroccoliTree;}

transpileTree usage

// find the ember-cli-htmlbars addonlethtmlbarsAddon=this.addons.find(addon=>addon.name==='ember-cli-htmlbars');// invoke .transpileTree passing in the custom input treelettranspiledCustomTree=htmlbarsAddon.transpileTree(someCustomTree);

Adding Custom Plugins

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.

varSomeTransform=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);}};

Options for registering a plugin

• name - String. The name of the AST transform for debugging purposes.
• plugin - A function of type ASTPluginBuilder.
• 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).

Implementing Dependency Invalidation in an AST Plugin

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";exporttypeASTDependencyPlugin=ASTPluginWithDepsBuilder|ASTPluginBuilderWithDeps;exportinterfaceASTPluginWithDepsBuilder{(env: ASTPluginEnvironment): ASTPluginWithDeps;}exportinterfaceASTPluginBuilderWithDepsextendsASTPluginBuilder{/** * @see {ASTPluginWithDeps.dependencies} below. **/dependencies(relativePath): string[];}exportinterfaceASTPluginWithDepsextendsASTPlugin{/** * 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[];}

Precompile HTMLBars template strings within other addons

module.exports={name: 'my-addon-name',setupPreprocessorRegistry: function(type,registry){varhtmlbarsPlugin=registry.load('template').find(function(plugin){returnplugin.name==='ember-cli-htmlbars';});// precompile any htmlbars template string via the precompile method on the// ember-cli-htmlbars plugin wrapper; `precompiled` will be a string of the// form://// Ember.HTMLBars.template(function() {...})//varprecompiled=htmlbarsPlugin.precompile("{{my-component}}");}};

Custom Template Compiler

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.jsmodule.exports=function(defaults){letapp=newEmberApp(defaults,{'ember-cli-htmlbars': {templateCompilerPath: `some_path/to/ember-template-compiler.js`,}});};

Using as a Broccoli Plugin

varHtmlbarsCompiler=require('ember-cli-htmlbars');vartemplateTree=newHtmlbarsCompiler('app/templates',{isHTMLBars: true,// provide the templateCompiler that is paired with your Ember versiontemplateCompiler: require('./bower_components/ember/ember-template-compiler')});