babel-plugin-htmlbars-inline-precompile

5.3.1 verified Sat Apr 25 auth: no javascript

Babel plugin to replace tagged template strings or function calls with precompiled HTMLBars templates, primarily used in Ember.js applications. Current stable version is 5.3.1, released on a monthly cadence. Key differentiator: it allows inline HBS templates in tests and code, which get precompiled at build time. Alternative to ember-cli-htmlbars for non-Ember projects, but tightly coupled to Ember's template compiler. Requires Node 10+, Ember 2.10+, and Babel 7. Notable breaking change in v5.0.0: renamed `scope` option to `locals`.

Common errors

error Cannot find module 'babel-plugin-htmlbars-inline-precompile' ↓

cause Plugin not installed or not in node_modules.

fix

Run npm install --save-dev babel-plugin-htmlbars-inline-precompile.

error TypeError: Cannot read property 'precompile' of undefined ↓

cause The `precompile` option was not provided or points to an invalid object.

fix

Ensure you pass a valid precompile function, e.g., from @glimmer/compiler: precompile: require('@glimmer/compiler').precompile.

error Error: hbs is not a function ↓

cause Using `hbs` as a regular function without the plugin configured or using it outside of Babel-transformed code.

fix

Ensure the Babel plugin is configured correctly and that code with hbs is being transpiled by Babel.

Warnings

breaking In v5.0.0, the `scope` option was renamed to `locals`. ↓

fix Replace any usage of `scope` with `locals` in plugin options.

gotcha The plugin relies on Babel 7; using Babel 6 will cause errors. ↓

fix Upgrade to Babel 7 and use babel-plugin-htmlbars-inline-precompile >=3.0.0.

gotcha The import `import hbs from 'htmlbars-inline-precompile'` is a default export, but some bundlers may require `.default` when using CommonJS require. ↓

fix Use ESM imports. If using CommonJS, write `const hbs = require('htmlbars-inline-precompile').default`.

deprecated Passing `precompile` directly as an option is still supported but `templateCompilerPath` is preferred since v5. ↓

fix Use `templateCompilerPath` option to specify path to template compiler.

Install

npm install babel-plugin-htmlbars-inline-precompile

yarn add babel-plugin-htmlbars-inline-precompile

pnpm add babel-plugin-htmlbars-inline-precompile

Imports

hbs
wrong
```
const hbs = require('htmlbars-inline-precompile').default
```
correct
```
import hbs from 'htmlbars-inline-precompile'
```
Default export from 'htmlbars-inline-precompile'. ESM-only; CommonJS require may not work in all packagers.
babel-plugin-htmlbars-inline-precompile
wrong
```
plugins: ['babel-plugin-htmlbars-inline-precompile']
```
correct
```
plugins: [['babel-plugin-htmlbars-inline-precompile', { precompile: ... }]]
```
Plugin requires options object with `precompile` function (or `templateCompilerPath` since v5). Without options, the plugin has no effect.
precompile
wrong
```
import { precompile } from 'babel-plugin-htmlbars-inline-precompile';
```
correct
```
import { precompile } from '@glimmer/compiler';
```
The precompile function comes from Ember's template compiler (e.g., @glimmer/compiler or ember-source), not from this plugin.

Quickstart

Shows Babel plugin setup and usage of hbs tagged template for inline compiled templates.

// Install: npm install --save-dev babel-plugin-htmlbars-inline-precompile htmlbars-inline-precompile
// Configure Babel plugin in babel.config.js:
module.exports = function(api) {
  api.cache(true);
  return {
    plugins: [
      ['babel-plugin-htmlbars-inline-precompile', {
        precompile: require('@glimmer/compiler').precompile,
        // or use templateCompilerPath option:
        // templateCompilerPath: 'path/to/ember-template-compiler.js'
      }]
    ]
  };
};

// In your test file:
import hbs from 'htmlbars-inline-precompile';
import { render } from '@ember/test-helpers';

await render(hbs`<p>Hello {{name}}!</p>`);