babel-plugin-ember-template-compilation

What is babel-plugin-ember-template-compilation?

The babel-plugin-ember-template-compilation package is a Babel plugin designed to precompile Ember.js templates. This plugin allows developers to write templates in a more concise and readable format, which are then compiled into JavaScript functions that can be used within Ember applications.

What are babel-plugin-ember-template-compilation's main functionalities?

Precompiling Templates

This feature allows you to precompile Ember.js templates using the Ember template compiler. The precompiled templates are then transformed into JavaScript functions that can be used within your Ember application.

module.exports = function (babel) {
  return {
    plugins: [
      ['babel-plugin-ember-template-compilation', {
        precompile: require('ember-source/dist/ember-template-compiler').precompile
      }]
    ]
  };
};

Custom Template Compiler

This feature allows you to use a custom template compiler instead of the default Ember template compiler. This can be useful if you have specific requirements for how your templates should be compiled.

module.exports = function (babel) {
  return {
    plugins: [
      ['babel-plugin-ember-template-compilation', {
        precompile: customTemplateCompiler
      }]
    ]
  };
};

function customTemplateCompiler(templateString) {
  // Custom compilation logic
  return compiledTemplate;
}

Other packages similar to babel-plugin-ember-template-compilation

ember-cli-htmlbars

The ember-cli-htmlbars package is an Ember CLI addon that provides a preprocessor for compiling Handlebars templates in Ember.js applications. It is similar to babel-plugin-ember-template-compilation in that it precompiles templates, but it is specifically designed to work with Ember CLI and integrates more tightly with the Ember build process.

babel-plugin-htmlbars-inline-precompile

The babel-plugin-htmlbars-inline-precompile package is a Babel plugin that allows you to precompile Handlebars templates inline within JavaScript files. It is similar to babel-plugin-ember-template-compilation in that it precompiles templates, but it is designed to be used directly within JavaScript files rather than as part of a broader build process.

README

babel-plugin-ember-template-compilation

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

Requirements

• Node 12+ (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 need to either 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" 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

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

• Edward Faulkner (@ef4)
• Dan Freeman (@dfreeman)