ember-cli-htmlbars

7.0.1 verified Sat Apr 25 auth: no javascript

An Ember CLI addon that compiles Handlebars/HTMLBars templates into JavaScript functions using the Glimmer VM. Current stable version is 7.0.1 (March 2026). It integrates with Ember's build pipeline, supporting AST transforms, custom template compilers, and dependency invalidation. It requires Ember.js v4.12+ and Node.js 20+. Key differentiators: tight integration with Ember CLI, first-party support for addon template compilation, and advanced AST plugin system.

Common errors

error TypeError: this.app.registry.add is not a function ↓

cause `included` hook called before `this._super.included`

fix

Ensure this._super.included.apply(this, arguments) is called before accessing this.app.registry.

error Cannot find module 'ember-cli-htmlbars' ↓

cause Package not installed or not in `devDependencies`

fix

Run npm install --save-dev ember-cli-htmlbars or yarn add --dev ember-cli-htmlbars.

error Error: Template compilation failed: Unexpected token ↓

cause AST transform plugin returns invalid Handlebars AST

fix

Ensure the AST transform returns a valid node or use Glimmer/HTMLBars transformer API.

error TypeError: (0 , _emberCliHtmlbars.default) is not a function ↓

cause Using CommonJS require with a default import in ESM project

fix

Use import HtmlbarsCompiler from 'ember-cli-htmlbars' instead of require.

Warnings

breaking Version 7.0.0 dropped support for Node < 18 and Ember < 4.12. ↓

fix Upgrade Node.js to >=18 and Ember.js to >=4.12.

breaking Version 7.0.0 updated minimum Node version to 20. ↓

fix Upgrade Node.js to >=20.

breaking Version 6.0.0 simplified babel plugin usage, dropping support for ember < 3.27. ↓

fix Upgrade Ember to >=3.27. If on older Ember, stay on v5.x.

gotcha When registering AST plugins, do not call `new` on the plugin function; pass it directly. ↓

fix Use `plugin: SomeTransform` not `plugin: new SomeTransform()`.

gotcha In TypeScript, `TemplateFactory` type cannot be constructed; use only for type annotations. ↓

fix Use `import type { TemplateFactory } from 'ember-cli-htmlbars'` to avoid runtime errors.

deprecated Custom template compiler path via `templateCompilerPath` option is deprecated since v6. ↓

fix Use `babel-plugin-ember-template-compilation` or upgrade to new simplified pipeline.

Install

npm install ember-cli-htmlbars

yarn add ember-cli-htmlbars

pnpm add ember-cli-htmlbars

Imports

default
wrong
```
const HtmlbarsCompiler = require('ember-cli-htmlbars').default
```
correct
```
import HtmlbarsCompiler from 'ember-cli-htmlbars'
```
Default export is the Broccoli plugin class. In TypeScript, use import statement; no .default needed.

TemplateFactory

wrong

const { TemplateFactory } = require('ember-cli-htmlbars')

correct

import { TemplateFactory } from 'ember-cli-htmlbars'

Named export available in v6.3.0+. Not user-constructible; used for typing.

type TemplateFactory

wrong

import { TemplateFactory } from 'ember-cli-htmlbars' (runtime import)

correct

import type { TemplateFactory } from 'ember-cli-htmlbars'

If only using for type annotations, use import type to avoid side effects.

Quickstart

Shows how to register an AST transform plugin in an Ember addon using ember-cli-htmlbars.

// Use ember-cli-htmlbars via Ember CLI build pipeline
// No direct import needed in app code; addon is picked up automatically.
// To register an AST transform in an addon:
import SomeTransform from './some-path/transform';
export default {
  name: 'my-addon',
  included() {
    this._super.included.apply(this, arguments);
    this.app.registry.add('htmlbars-ast-plugin', {
      name: 'some-transform',
      plugin: SomeTransform,
      baseDir() { return __dirname; },
      cacheKey() { return SomeTransform.cacheKey; }
    });
  }
};