Babel AST Utilities

Common errors

• TypeError: t.someBuilder is not a function

  cause Attempting to use `babel-types` builder or checker methods after incorrectly importing the package, typically with a default import instead of a namespace import.
  fix Use a namespace import: `import * as t from '@babel/types';` if using ESM, or `const t = require('@babel/types');` if using CommonJS.

• Error: Unknown node type: 'MyCustomNode'

  cause Attempting to create an AST node type (e.g., `t.myCustomNode()`) that is not a valid ESTree or Babel-specific AST node type, or is not supported by the specific Babel version being used.
  fix Consult the official `@babel/types` API documentation or ESTree specification to ensure all created node types are valid and supported. Ensure your Babel version is up-to-date if you are trying to use newer syntax features.

• Invariant Violation: someProperty must be a(n) string (or similar type mismatch)

  cause Providing an argument of the wrong JavaScript type or an invalid value to a `babel-types` builder function, which expects specific types for its parameters (e.g., passing a number where a string is expected for an identifier name).
  fix Review the `@babel/types` API documentation for the specific builder function (`t.someBuilder(param1, param2...)`) to understand the expected types and structure of its arguments and adjust your code accordingly.

Warnings

• breaking Babel v8 has removed support for TypeScript's deprecated `module <identifier>` syntax (namespace imports) in `@babel/types` and related packages.
  Fix: Migrate TypeScript code to use ES Modules syntax (e.g., `import * as MyModule from './module';`) or `declare module` blocks for ambient declarations instead of the legacy `module <identifier> { ... }` syntax.
• breaking For Babel v8, `@babel/types` has removed legacy `.d.ts` files for TypeScript versions older than 4.0. Projects using older TypeScript versions will encounter type errors.
  Fix: Upgrade your project's TypeScript version to 4.0 or newer to ensure compatibility with `@babel/types` v8 type definitions.
• gotcha Babel v8 is progressively removing deprecated default exports across its monorepo packages. While `@babel/types` primarily uses named exports (accessed via `import * as t from '@babel/types'`), users should be aware that other `@babel` packages may now strictly require named imports.
  Fix: Always prefer namespace imports (`import * as t from 'pkg';`) or explicit named imports (`import { SomeExport } from 'pkg';`) over default imports (`import SomeExport from 'pkg';`) for `@babel` packages in Babel v8 and newer to avoid runtime errors, especially for packages that previously had a default export.
• gotcha Using a `@babel/types` version that is significantly different from other `@babel` core packages (like `@babel/parser`, `@babel/traverse`, or `@babel/generator`) can lead to AST incompatibility issues or unexpected behavior, as AST node definitions and structures evolve across Babel versions.
  Fix: Always ensure that all `@babel/*` packages in your project are installed with compatible versions, ideally by installing the latest major version for all of them or allowing your package manager to resolve compatible versions within the same major range (e.g., `^7.0.0`).

Install

• npm install babel-types npm
• yarn add babel-types yarn
• pnpm add babel-types pnpm

Imports

• t
  wrong:

  import t from '@babel/types';

  correct:

  import * as t from '@babel/types';

  The `@babel/types` package exports an object containing all AST builder and checker methods. It is common practice to import this object as `t` via a namespace import. Direct default imports are not supported.
• Node

  import type { Node } from '@babel/types';

  For TypeScript usage, `Node` is the base interface for all AST nodes, useful for general type annotations in functions that operate on ASTs. Other specific node types like `Identifier`, `Expression`, etc., can also be imported this way.
• ArrowFunctionExpression

  import type { ArrowFunctionExpression } from '@babel/types';

  Specific AST node interfaces can be imported as types for precise TypeScript type hinting, ensuring type safety when working with Babel's AST structures.

Quickstart

This quickstart demonstrates how to programmatically construct an Abstract Syntax Tree (AST) representing a simple JavaScript arrow function `const add = (a, b) => a + b;` using `babel-types`. It shows the creation of identifiers, expressions, statements, and a full function declaration, then uses `@babel/generator` to convert the AST back into code.

import * as t from '@babel/types';
import generate from '@babel/generator';

// Create identifiers for 'a' and 'b'
const paramA = t.identifier('a');
const paramB = t.identifier('b');

// Create a binary expression 'a + b'
const sumExpression = t.binaryExpression('+', paramA, paramB);

// Create a return statement for 'a + b'
const returnStatement = t.returnStatement(sumExpression);

// Create a block statement for the function body
const functionBody = t.blockStatement([returnStatement]);

// Create an arrow function expression '(...params) => { ...body }'
const arrowFunction = t.arrowFunctionExpression(
  [paramA, paramB], // params
  functionBody,     // body
  false             // async
);

// Create a variable declarator: 'add = (...)'
const declarator = t.variableDeclarator(t.identifier('add'), arrowFunction);

// Create a variable declaration: 'const add = (...)'
const variableDeclaration = t.variableDeclaration('const', [declarator]);

// Wrap the declaration in a Program node
const program = t.program([variableDeclaration]);

// Generate code from the AST (requires @babel/generator)
const { code } = generate(program);
console.log(code);
// Expected output: const add = (a, b) => a + b;