Package detail

babel-plugin-ember-template-compilation

emberjs744.4kMIT3.0.0

Babel implementation of Ember's low-level template-compilation API

readme

babel-plugin-ember-template-compilation

Build Status

Babel plugin that implements Ember's low-level template-compilation API.

Requirements

  • Node 18+ (when used in Node, but we also support in-browser usage)
  • Babel 7
  • the output works with ember-source 3.27+. For older Ember versions, see babel-plugin-htmlbars-inline-precompile instead.

Usage

This plugin implements precompileTemplate from RFC 496:

import { precompileTemplate } from '@ember/template-compilation';

For backward compatibility, it also has an enableLegacyModules option that can enable each of these widely-used older patterns:

import { hbs } from 'ember-cli-htmlbars';
import hbs from 'ember-cli-htmlbars-inline-precompile';
import hbs from 'htmlbars-inline-precompile';

Common Options

This package has both a Node implementation and a portable implementation that works in browsers.

The exported modules are:

  • babel-plugin-ember-template-compilation: automatically chooses between the node and browser implementations (using package.json exports feature).
  • babel-plugin-ember-template-compilation/browser: the core implementation that works in browsers (and anywhere else) without using any Node-specific APIs.
  • babel-plugin-ember-template-compilation/node: the Node-specific implementation that adds the ability to automatically load plugins from disk, etc.

The options are:

interface Options {
  // The ember-template-compiler.js module that ships within your ember-source version. In the browser implementation, this is mandatory. In the Node implementation you can use compilerPath instead.
  compiler?: EmberTemplateCompiler;

  // The on-disk path to the ember-template-compiler.js module for our current
  // ember version. You may set `compilerPath` or set `compiler`.
  // This will get resolved from the current working directory, so a package name
  // like "ember-source/dist/ember-template-compiler" (the default value) is acceptable.
  compilerPath?: string;

  // Allows you to remap what imports will be emitted in our compiled output. By
  // example:
  //
  //   outputModuleOverrides: {
  //     '@ember/template-factory': {
  //       createTemplateFactory: ['createTemplateFactory', '@glimmer/core'],
  //     }
  //   }
  //
  // Normal Ember apps shouldn't need this, it exists to support other
  // environments like standalone GlimmerJS
  outputModuleOverrides?: Record<string, Record<string, [string, string]>>;

  // By default, this plugin implements only Ember's stable public API for
  // template compilation, which is:
  //
  //    import { precompileTemplate } from '@ember/template-compilation';
  //
  // But historically there are several other importable syntaxes in widespread
  // use, and we can enable those too by including their module names in this
  // list. See `type LegacyModuleName` below.
  enableLegacyModules?: LegacyModuleName[];

  // Controls the output format.
  //
  //  "wire": The default. In the output, your templates are ready to execute in
  //  the most performant way.
  //
  //  "hbs": In the output, your templates will still be in HBS format.
  //  Generally this means they will still need further processing before
  //  they're ready to execute. The purpose of this mode is to support things
  //  like codemods and pre-publication transformations in libraries.
  targetFormat?: 'wire' | 'hbs';

  // Optional list of custom transforms to apply to the handlebars AST before
  // compilation. See `type Transform` below.
  transforms?: Transform[];
}

// The legal legacy module names. These are the only ones that are supported,
// because these are the ones in widespread community use. We don't want people
// creating new ones -- prefer `@ember/template-compilation` in new code.
type LegacyModuleName =
  | 'ember-cli-htmlbars'
  | 'ember-cli-htmlbars-inline-precompile'
  | 'htmlbars-inline-precompile';

// Each transform can be
//   - the actual AST transform function (this is the only kind that works in non-Node environments)
//   - a path to a module where we will find the AST transform function as the default export
//   - an array of length two containing the path to a module and an arguments object.
//       In this case we will pass the arguments to the default export from the module and
//       it should return the actual AST transform function.
// All the path resolving happens relative to the current working directory and
// respects node_modules resolution.
type Transform = Function | string | [string, unknown];

JSUtils: Manipulating Javascript from within AST transforms

AST transforms are plugins for modifying HBS templates at build time. Because those templates are embedded in Javascript and can access the Javascript scope, an AST plugin may want to introduce some new things into Javascript scope. That is what the JSUtils API is for.

Your AST transform can access the JSUtils API via env.meta.jsutils. Here's an example transform.

function myAstTransform(env) {
  return {
    name: 'my-ast-transform',
    visitor: {
      PathExpression(node, path) {
        if (node.original === 'onePlusOne') {
          let name = env.meta.jsutils.bindExpression('1+1', path, { nameHint: 'two' });
          return env.syntax.builders.path(name);
        }
      },
    },
  };
}

The example transform above would rewrite:

import { precompileTemplate } from '@ember/template-compilation';
precompileTemplate('<Counter @value={{onePlusOne}} />>');

To:

import { precompileTemplate } from '@ember/template-compilation';
let two = 1 + 1;
precompileTemplate('<Counter @value={{two}} />', { scope: () => ({ two }) });

See the jsdoc comments in js-utils.js for details on the methods available.

Acknowledgement / History

This repo derives from https://github.com/ember-cli/babel-plugin-htmlbars-inline-precompile

changelog

Changelog

Release (2025-05-06)

:boom: Breaking Change

  • babel-plugin-ember-template-compilation

Committers: 1

  • Edward Faulkner (@ef4)

Release (2025-04-01)

  • babel-plugin-ember-template-compilation 3.0.0-alpha.4 (patch)

:bug: Bug Fix

  • babel-plugin-ember-template-compilation
    • #91 Don't accidentally load ambient config during bindExpression (@ef4)

Committers: 1

  • Edward Faulkner (@ef4)

Release (2025-03-28)

  • babel-plugin-ember-template-compilation 3.0.0-alpha.3 (patch)

:bug: Bug Fix

  • babel-plugin-ember-template-compilation
    • #89 bugfix: wire is the default outputFormat (@ef4)

Committers: 1

  • Edward Faulkner (@ef4)

Release (2025-03-28)

  • babel-plugin-ember-template-compilation 3.0.0-alpha.2 (patch)

:bug: Bug Fix

  • babel-plugin-ember-template-compilation
    • #88 Fix a windows import bug (@ef4)

:house: Internal

  • babel-plugin-ember-template-compilation
    • #87 Windows tests (@ef4)
    • #85 Replace eslint-plugin-node with eslint-plugin-n (@ef4)

Committers: 1

  • Edward Faulkner (@ef4)

Release (2025-03-26)

  • babel-plugin-ember-template-compilation 3.0.0-alpha.1 (major)

:bug: Bug Fix

  • babel-plugin-ember-template-compilation
    • #83 Don't try to auto-detect ember template compiler when targetFormat do… (@ef4)

Committers: 1

  • Edward Faulkner (@ef4)

Release (2025-03-26)

babel-plugin-ember-template-compilation 2.4.1 (patch)

:bug: Bug Fix

  • babel-plugin-ember-template-compilation
    • #80 Fix incorrect "this" binding when there's a TypeScript this arg in scope (@ef4)

Committers: 1

  • Edward Faulkner (@ef4)

Release (2025-03-25)

  • babel-plugin-ember-template-compilation 3.0.0-alpha.0 (major)

:boom: Breaking Change

  • babel-plugin-ember-template-compilation

Committers: 1

  • Edward Faulkner (@ef4)

Release (2025-03-20)

babel-plugin-ember-template-compilation 2.4.0 (minor)

:rocket: Enhancement

:bug: Bug Fix

  • babel-plugin-ember-template-compilation

:house: Internal

  • babel-plugin-ember-template-compilation
    • #73 Make our tests use async babel (@ef4)

Committers: 2

Release (2024-09-09)

babel-plugin-ember-template-compilation 2.3.0 (minor)

:rocket: Enhancement

  • babel-plugin-ember-template-compilation
    • #62 Provide a default compilerPath (@ef4)

:house: Internal

  • babel-plugin-ember-template-compilation

Committers: 2

Release (2024-05-10)

babel-plugin-ember-template-compilation 2.2.5 (patch)

:bug: Bug Fix

  • babel-plugin-ember-template-compilation
    • #53 Problem with generating scope locals (the wire format array) when scope bag (the object) has aliasing properties (non-shorthand) (@NullVoxPopuli)
    • #54 fix 🎬 2 (@patricklx)

:house: Internal

  • babel-plugin-ember-template-compilation
    • #55 replace babel.parse with babel.template.expression.ast (@patricklx)

Committers: 2

Release (2024-05-08)

babel-plugin-ember-template-compilation 2.2.4 (patch)

:bug: Bug Fix

  • babel-plugin-ember-template-compilation

Committers: 1

Release (2024-05-03)

babel-plugin-ember-template-compilation 2.2.3 (patch)

:bug: Bug Fix

  • babel-plugin-ember-template-compilation

:house: Internal

Committers: 2

v2.2.2 (2024-04-17)

:bug: Bug Fix

Committers: 1

v2.2.1 (2023-11-01)

:bug: Bug Fix

  • #32 Preserve used imports when interoperating with transform-typescript (@patricklx, @ef4)

Committers: 1

v2.2.0 (2023-08-03)

:rocket: Enhancement

  • #28 Don't require compiler when targetFormat='hbs' (@ef4)

:house: Internal

Committers: 1

  • Edward Faulkner (@ef4)

v2.1.1 (2023-07-15)

:house: Internal

  • #26 Update babel-import-util (@ef4)

Committers: 1

  • Edward Faulkner (@ef4)

v2.1.0 (2023-07-08)

:rocket: Enhancement

:bug: Bug Fix

  • #25 Don't bring a separate @babel/traverse (@ef4)
  • #24 fix: @babel/traverse is a dependency not a dev-dependency (@runspired)

Committers: 3

v2.0.3 (2023-05-19)

:bug: Bug Fix

  • #20 Fix entity encoding in source-to-source mode (@ef4)

Committers: 1

  • Edward Faulkner (@ef4)

v2.0.2 (2023-04-05)

:bug: Bug Fix

  • #19 Replace Identifier only if key and value are different in the scope (@candunaj)

Committers: 1

v2.0.1 (2023-04-04)

:bug: Bug Fix

  • #17 PrecompileTemplate with scope that has properties with different key and value (@candunaj)
  • #12 Handle coverage annotation in scope function (@wagenet)

:house: Internal

Committers: 4

v2.0.0 (2022-11-17)

:rocket: Enhancement

  • #5 Allow AST plugins to manipulate Javascript scope (@ef4 and (@dfreeman))
  • #9 Source to Source mode (@ef4)

:boom: Breaking

  • #9 Source to Source mode: caused a change to the options format, since we now need the whole ember-template-compiler.js module, not just the precompile function from that module.

Committers: 2

v1.0.2 (2022-04-11)

:house: Internal

  • #4 Upgrading dependencies (@ef4)

Committers: 1

  • Edward Faulkner (@ef4)

v1.0.1 (2021-11-04)

:bug: Bug Fix

  • #1 Ensure babel.parse does not use top level babel config. (@rwjblue)

:house: Internal

  • #2 Ensure yarn.lock is always in sync (@rwjblue)

Committers: 1

v5.3.0 (2021-04-12)

:rocket: Enhancement

:house: Internal

Committers: 2

v5.2.2 (2021-04-01)

:bug: Bug Fix

Committers: 1

v5.2.1 (2021-03-24)

:bug: Bug Fix

  • #368 Account for comments in preprocessor for proposals (@pzuraq)

Committers: 1

v5.2.0 (2021-03-24)

:rocket: Enhancement

  • #361 Add preprocessEmbeddedTemplates function (@pzuraq)
  • #362 Allow usage of proposals to be used in arbitrary expression positions (@pzuraq)

Committers: 1

v5.1.0 (2021-03-23)

:rocket: Enhancement

  • #360 Add ability to parse scope function (allow strict mode templates to be more resilient to module cycles). (@pzuraq)

:bug: Bug Fix

  • #359 Ensure locals are used instead of scope everywhere (@pzuraq)

Committers: 1

v5.0.0 (2021-03-17)

:boom: Breaking Change

  • #358 Rename scope to locals for strict mode transpilation (@pzuraq)

:rocket: Enhancement

Committers: 1

v4.4.6 (2021-03-17)

:bug: Bug Fix

  • #357 [BUGFIX] Use a unique identifier for each reference (@pzuraq)

Committers: 1

v4.4.5 (2021-03-12)

:bug: Bug Fix

  • #355 Avoid sharing list of previously added imports. (@rwjblue)

Committers: 1

v4.4.4 (2021-02-25)

:bug: Bug Fix

Committers: 1

v4.4.3 (2021-02-24)

:bug: Bug Fix

Committers: 1

v4.4.2 (2021-02-24)

:bug: Bug Fix

  • #347 Default ensureModuleApiPolyfill to true (@pzuraq)

Committers: 1

v4.4.1 (2021-02-24)

:bug: Bug Fix

  • #346 Ensure proposal syntaxes work with Ember module API polyfill (@pzuraq)

Committers: 1

v4.4.0 (2021-02-23)

:rocket: Enhancement

  • #339 Add moduleOverrides options (@pzuraq)
  • #338 Refactor to use createTemplateFactory (@pzuraq)
  • #336 Implements an option to support the template tag imports proposal (@pzuraq)

Committers: 1

v4.3.0 (2021-02-22)

:rocket: Enhancement

  • #335 Implements an option to support the template literal imports proposal (@pzuraq)
  • #334 Add support for multiple imports (@pzuraq)
  • #333 [FEAT] Add shouldParseScope, disableTemplateTag, disableFunctionCall options (@pzuraq)
  • #332 Adds useEmberModule option (@pzuraq)

Committers: 1

v4.2.1 (2020-11-09)

:bug: Bug Fix

  • #297 Fix issues when using emoji in templates while transpiling for IE11 (@rwjblue)

Committers: 1

v4.2.0 (2020-08-10)

:rocket: Enhancement

Committers: 2

v4.1.0 (2020-05-07)

:rocket: Enhancement / :bug: Fix

  • #216 Avoid assuming ember-template-compiler result is JSON (@rwjblue)

Committers: 1

v4.0.1 (2020-05-06)

:bug: Bug Fix

Committers: 1

v4.0.0 (2020-05-06)

:boom: Breaking Change

:house: Internal

  • #211 Update release automation dependencies and settings. (@rwjblue)

Committers: 2

v3.1.0 (2020-05-06)

:rocket: Enhancement

  • #208 Add ability to transfer compilation errors into runtime. (@rwjblue)

:house: Internal

Committers: 2

v3.0.1 (2019-12-11)

:bug: Bug Fix

  • #134 Ensure */ included in a template does break surrounding JS. (@rwjblue)

Committers: 1

v3.0.0 (2019-10-01)

  • Released in order to avoid incompatibilities between ember-cli-htmlbars and ember-cli-htmlbars-inline-precompile. Contains no changes from prior version.

v2.1.1 (2019-09-29)

:bug: Bug Fix

  • #104 Ensure JSON.stringify'ed value is valid for hbs() options. (@rwjblue)

Committers: 1

v2.1.0 (2019-09-09)

:rocket: Enhancement

Committers: 2

v2.0.0 (2019-08-30)

:boom: Breaking Change

:rocket: Enhancement

  • #89 Add an inline comment with the original template. (@rwjblue)
  • #75 Add ability to pass static options to transpilation. (@rwjblue)
  • #42 Test templates from MU co-located tests (@NullVoxPopuli)

:memo: Documentation

:house: Internal

Committers: 5

v0.2.5 (2018-06-02)

Full Changelog

Implemented enhancements:

  • Pass through content to precompile. #37 (rwjblue)

Merged pull requests:

v0.2.4 (2018-03-22)

Full Changelog

Implemented enhancements:

Merged pull requests:

v0.1.1 (2017-07-21)

Full Changelog

Implemented enhancements:

  • CI: Use "auto-dist-tag" for deployment #24 (Turbo87)

Merged pull requests:

v0.2.3 (2017-03-13)

Full Changelog

Merged pull requests:

  • Avoid error when processing expressions before import has ocurred. #23 (rwjblue)

v0.2.2 (2017-03-13)

Full Changelog

Merged pull requests:

  • Add failing test for usage after modules transform. #22 (rwjblue)

v0.2.1 (2017-03-11)

Full Changelog

Merged pull requests:

  • Refactor to work when before babel-plugin-transform-es2015-template-literals. #21 (rwjblue)

v0.2.0 (2017-03-11)

Full Changelog

Closed issues:

  • An in-range update of babel-core is breaking the build 🚨 #18
  • needs to support caching #17

Merged pull requests:

  • Add basic caching for babel@6 usage. #20 (rwjblue)
  • CI: Enable automatic NPM deployment for tags #19 (Turbo87)

v0.1.0 (2016-08-10)

Full Changelog

Implemented enhancements:

  • will be improved by #3
  • Cleanup & referencesImport() #13 (Turbo87)

Closed issues:

  • Migrate to ember-cli org? #14
  • placeholders inside a tagged template string are not supported #9

Merged pull requests:

0.0.5 (2015-07-10)

Full Changelog

Merged pull requests:

  • Allow single string as argument for hbs #7 (pangratz)

0.0.4 (2015-06-30)

Full Changelog

v0.0.3 (2015-06-26)

Full Changelog

Closed issues:

  • Babel deprecation with 5.6.14 - Use path.replaceWithSourceString. #5

Merged pull requests:

  • Use path.replaceWithSourceString to avoid deprecation. #6 (rwjblue)

v0.0.2 (2015-06-13)

Full Changelog

Merged pull requests:

  • Replace remove() with dangerouslyRemove() #4 (alisdair)

v0.0.1 (2015-05-06)

* _This Change Log was automatically generated by github_changelog_generator_