{"id":18303,"library":"ember-cli-htmlbars","title":"ember-cli-htmlbars","description":"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.","status":"active","version":"7.0.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/ember-cli/ember-cli-htmlbars","tags":["javascript","ember-addon","ember-cli","typescript"],"install":[{"cmd":"npm install ember-cli-htmlbars","lang":"bash","label":"npm"},{"cmd":"yarn add ember-cli-htmlbars","lang":"bash","label":"yarn"},{"cmd":"pnpm add ember-cli-htmlbars","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Babel transformation","package":"@babel/core","optional":false},{"reason":"Required as peer dependency for template compilation","package":"ember-source","optional":false},{"reason":"Used for simplified template compilation on Ember 3.27+","package":"babel-plugin-ember-template-compilation","optional":true}],"imports":[{"note":"Default export is the Broccoli plugin class. In TypeScript, use import statement; no .default needed.","wrong":"const HtmlbarsCompiler = require('ember-cli-htmlbars').default","symbol":"default","correct":"import HtmlbarsCompiler from 'ember-cli-htmlbars'"},{"note":"Named export available in v6.3.0+. Not user-constructible; used for typing.","wrong":"const { TemplateFactory } = require('ember-cli-htmlbars')","symbol":"TemplateFactory","correct":"import { TemplateFactory } from 'ember-cli-htmlbars'"},{"note":"If only using for type annotations, use import type to avoid side effects.","wrong":"import { TemplateFactory } from 'ember-cli-htmlbars' (runtime import)","symbol":"type TemplateFactory","correct":"import type { TemplateFactory } from 'ember-cli-htmlbars'"}],"quickstart":{"code":"// Use ember-cli-htmlbars via Ember CLI build pipeline\n// No direct import needed in app code; addon is picked up automatically.\n// To register an AST transform in an addon:\nimport SomeTransform from './some-path/transform';\nexport default {\n  name: 'my-addon',\n  included() {\n    this._super.included.apply(this, arguments);\n    this.app.registry.add('htmlbars-ast-plugin', {\n      name: 'some-transform',\n      plugin: SomeTransform,\n      baseDir() { return __dirname; },\n      cacheKey() { return SomeTransform.cacheKey; }\n    });\n  }\n};","lang":"typescript","description":"Shows how to register an AST transform plugin in an Ember addon using ember-cli-htmlbars."},"warnings":[{"fix":"Upgrade Node.js to >=18 and Ember.js to >=4.12.","message":"Version 7.0.0 dropped support for Node < 18 and Ember < 4.12.","severity":"breaking","affected_versions":"<7.0.0"},{"fix":"Upgrade Node.js to >=20.","message":"Version 7.0.0 updated minimum Node version to 20.","severity":"breaking","affected_versions":"<7.0.0"},{"fix":"Upgrade Ember to >=3.27. If on older Ember, stay on v5.x.","message":"Version 6.0.0 simplified babel plugin usage, dropping support for ember < 3.27.","severity":"breaking","affected_versions":"<6.0.0"},{"fix":"Use `plugin: SomeTransform` not `plugin: new SomeTransform()`.","message":"When registering AST plugins, do not call `new` on the plugin function; pass it directly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `import type { TemplateFactory } from 'ember-cli-htmlbars'` to avoid runtime errors.","message":"In TypeScript, `TemplateFactory` type cannot be constructed; use only for type annotations.","severity":"gotcha","affected_versions":">=6.3.0"},{"fix":"Use `babel-plugin-ember-template-compilation` or upgrade to new simplified pipeline.","message":"Custom template compiler path via `templateCompilerPath` option is deprecated since v6.","severity":"deprecated","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure `this._super.included.apply(this, arguments)` is called before accessing `this.app.registry`.","cause":"`included` hook called before `this._super.included`","error":"TypeError: this.app.registry.add is not a function"},{"fix":"Run `npm install --save-dev ember-cli-htmlbars` or `yarn add --dev ember-cli-htmlbars`.","cause":"Package not installed or not in `devDependencies`","error":"Cannot find module 'ember-cli-htmlbars'"},{"fix":"Ensure the AST transform returns a valid node or use Glimmer/HTMLBars transformer API.","cause":"AST transform plugin returns invalid Handlebars AST","error":"Error: Template compilation failed: Unexpected token"},{"fix":"Use `import HtmlbarsCompiler from 'ember-cli-htmlbars'` instead of `require`.","cause":"Using CommonJS require with a default import in ESM project","error":"TypeError: (0 , _emberCliHtmlbars.default) is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}