or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

builders.mdconfiguration.mdformatters.mdindex.md
tile.json

index.mddocs/

@babel/template

@babel/template provides utilities for generating Abstract Syntax Trees (ASTs) from string templates with placeholder replacement capabilities. It offers multiple template formatters for different AST node types and supports both string-based and template literal syntax, making it essential for building Babel plugins, code transformers, and other tools that need to programmatically generate JavaScript/TypeScript code.

Package Information

  • Package Name: @babel/template
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @babel/template

Core Imports

import template from "@babel/template";

For specific formatters:

import { smart, statement, statements, expression, program } from "@babel/template";

For types:

import type { Options, Replacements } from "@babel/template";

CommonJS:

const template = require("@babel/template").default;
const { smart, statement, statements, expression, program } = require("@babel/template");

Basic Usage

import template from "@babel/template";
import * as t from "@babel/types";

// Basic string template with placeholder replacement
const buildRequire = template(`
  const %%importName%% = require(%%source%%);
`);

const ast = buildRequire({
  importName: t.identifier("react"),
  source: t.stringLiteral("react")
});

// Template literal syntax
const buildFunction = template`
  function ${t.identifier("add")}(${t.identifier("a")}, ${t.identifier("b")}) {
    return ${t.identifier("a")} + ${t.identifier("b")};
  }
`;

const functionAst = buildFunction();

Architecture

@babel/template is built around several key components:

  • Template Builders: Factory functions that create template processors with specific output formatters
  • Formatters: Processing engines that determine output AST node types (smart, statement, statements, expression, program)
  • Template Processors: Handle both string-based templates and template literals with placeholder replacement
  • Options System: Configurable placeholder patterns, comment preservation, and parser options
  • AST Integration: Deep integration with @babel/types, @babel/parser, and @babel/code-frame

Capabilities

Template Builders

Core template building functionality that creates AST generators from string templates or template literals.

interface TemplateBuilder<T> {
  // Create new builder with merged options
  (opts: PublicOpts): TemplateBuilder<T>;
  // String template with optional options
  (tpl: string, opts?: PublicOpts): (replacements?: PublicReplacements) => T;
  // Template literal with placeholder arguments
  (tpl: TemplateStringsArray, ...args: Array<unknown>): (replacements?: PublicReplacements) => T;
  // Direct AST generation methods
  ast: {
    (tpl: string, opts?: PublicOpts): T;
    (tpl: TemplateStringsArray, ...args: Array<unknown>): T;
  };
}

Template Builders

Template Formatters

Built-in formatters that control the output AST node type and validation behavior.

// Smart formatter - returns single statement or array based on content
declare const smart: TemplateBuilder<t.Statement | t.Statement[]>;

// Single statement formatter - enforces exactly one statement
declare const statement: TemplateBuilder<t.Statement>;

// Multiple statements formatter - returns array of statements
declare const statements: TemplateBuilder<t.Statement[]>;

// Expression formatter - returns expression node
declare const expression: TemplateBuilder<t.Expression>;

// Program formatter - returns program node
declare const program: TemplateBuilder<t.Program>;

Formatters

Configuration Options

Template processing options for placeholder patterns, comment handling, and parser configuration.

interface PublicOpts {
  placeholderWhitelist?: Set<string>;
  placeholderPattern?: RegExp | false;
  preserveComments?: boolean;
  syntacticPlaceholders?: boolean | null;
  // Extends all @babel/parser ParserOptions
}

type PublicReplacements = { [x: string]: unknown } | Array<unknown>;

Configuration

Types

// Main template builder interface combining all formatters
interface DefaultTemplateBuilder extends TemplateBuilder<t.Statement | t.Statement[]> {
  smart: typeof smart;
  statement: typeof statement;
  statements: typeof statements;
  expression: typeof expression;
  program: typeof program;
  ast: typeof smart.ast;
}

// Exported type aliases for convenience
type Options = PublicOpts;
type Replacements = PublicReplacements;