Babel Plugin Transform Template Literals

Babel plugin that compiles ES2015 template literals to ES5-compatible code. Transforms both regular template literals (`hello ${name}`) and tagged template expressions (html`<div>${content}</div>`) into equivalent ES5 syntax while preserving JavaScript specification compliance for expression evaluation order.

Package Information

• Package Name: @babel/plugin-transform-template-literals
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev @babel/plugin-transform-template-literals

Core Imports

import templateLiterals from "@babel/plugin-transform-template-literals";

For CommonJS:

const templateLiterals = require("@babel/plugin-transform-template-literals");

Plugin Development Imports (for extending or understanding the plugin):

import { declare } from "@babel/helper-plugin-utils";
import { template, types as t, type NodePath } from "@babel/core";

Basic Usage

// Babel configuration (.babelrc or babel.config.js)
{
  "plugins": [
    "@babel/plugin-transform-template-literals"
  ]
}

// With options
{
  "plugins": [
    ["@babel/plugin-transform-template-literals", { "loose": true }]
  ]
}

Input (ES2015):

`Hello ${name}!`;
html`<div>${content}</div>`;

Output (ES5):

"Hello " + name + "!";
html(_templateObject || (_templateObject = _taggedTemplateLiteral(["<div>", "</div>"])), content);

Architecture

The plugin operates through Babel's AST transformation pipeline:

• Plugin Structure: Built using declare() from @babel/helper-plugin-utils with Babel version 7+ requirement
• AST Visitors: Two primary visitors handle TemplateLiteral and TaggedTemplateExpression nodes
• Transformation Strategy: Template literals become string concatenation or .concat() calls; tagged templates become function calls with template objects
• Helper Integration: Uses Babel runtime helpers (taggedTemplateLiteral, taggedTemplateLiteralLoose) for tagged template object creation
• Assumption Support: Respects Babel assumptions (ignoreToPrimitiveHint, mutableTemplateObject) for optimization
• Scope Management: Generates unique identifiers for template object caching to avoid collisions

Capabilities

Plugin Export

Main plugin function that creates the Babel plugin configuration.

/**
 * Default export function that creates the Babel plugin
 * Requires Babel version 7 or higher
 * @param api - Babel API object with version assertion and assumptions  
 * @param options - Plugin configuration options
 * @returns Babel plugin object with name and visitor configuration
 */
export default function(api: BabelAPI, options: Options): BabelPlugin;

interface BabelPlugin {
  name: "transform-template-literals";
  visitor: {
    TaggedTemplateExpression(path: NodePath<TaggedTemplateExpression>): void;
    TemplateLiteral(path: NodePath<TemplateLiteral>): void;
  };
}

Plugin Options

Configuration interface for customizing plugin behavior.

/**
 * Plugin configuration options
 */
export interface Options {
  /** Enable loose mode for more aggressive optimizations (default: false) */
  loose?: boolean;
}

Template Literal Transformation

Converts regular template literals to ES5-compatible string operations.

Transformation Logic:

• Simple templates: \hello ${name}`→"hello " + name`
• Complex templates: Uses .concat() method calls to preserve evaluation order
• Empty expressions: Automatically filtered out for cleaner output
• TypeScript literal types: Skipped (no transformation applied)

Options Impact:

• ignoreToPrimitiveHint: true: Uses binary + operators for concatenation
• ignoreToPrimitiveHint: false: Uses .concat() method calls to preserve primitive conversion order

Tagged Template Expression Transformation

Converts tagged template expressions to function calls with template objects.

Transformation Logic:

• Tagged templates: html`<div>${content}</div>` → html(templateObject, content)
• Template object caching: Creates unique identifiers to cache template objects
• Raw/cooked handling: Preserves differences between raw and cooked string values
• Helper selection: Uses taggedTemplateLiteral or taggedTemplateLiteralLoose based on mutableTemplateObject assumption

Options Impact:

• mutableTemplateObject: true: Uses taggedTemplateLiteralLoose helper for mutable template objects
• mutableTemplateObject: false: Uses taggedTemplateLiteral helper for immutable template objects

Types

/**
 * Babel API object provided to plugin functions
 */
interface BabelAPI {
  /** Assert that the Babel version meets requirements */
  assertVersion(version: number | string): void;
  /** Get assumption value with optional fallback */
  assumption(name: "ignoreToPrimitiveHint" | "mutableTemplateObject"): boolean | undefined;
}

/**
 * Generic AST node type
 */
interface Node {
  type: string;
}

/**
 * Generic expression node
 */
interface Expression extends Node {
  type: string;
}

/**
 * Babel scope for variable management
 */
interface Scope {
  generateUidIdentifier(name: string): Identifier;
  buildUndefinedNode(): Node;
  getProgramParent(): Scope;
  push(node: { id: Node }): void;
}

/**
 * Identifier AST node
 */
interface Identifier extends Expression {
  type: "Identifier";
  name: string;
}

/**
 * AST node path for template literals
 */
interface NodePath<T> {
  node: T;
  parent: Node;
  scope: Scope;
  get(key: string): NodePath | NodePath[];
  replaceWith(node: Node): void;
}

/**
 * Template literal AST node
 */
interface TemplateLiteral {
  type: "TemplateLiteral";
  quasis: TemplateElement[];
  expressions: Expression[];
}

/**
 * Tagged template expression AST node
 */
interface TaggedTemplateExpression {
  type: "TaggedTemplateExpression";
  tag: Expression;
  quasi: TemplateLiteral;
}

/**
 * Template element (string part) of template literal
 */
interface TemplateElement {
  value: {
    raw: string;
    cooked: string | null;
  };
}

Assumptions

The plugin respects two Babel assumptions that can be configured globally:

• ignoreToPrimitiveHint: When true, uses binary + operators instead of .concat() calls for better performance but less spec compliance
• mutableTemplateObject: When true, uses loose mode helpers that allow template object mutation for better performance

These assumptions can be set in Babel configuration or overridden by the plugin's loose option.