Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
t
✓ import * as t from '@babel/types';
✗ import 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.
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;
Debug
Known issues
breakingBabel v8 has removed support for TypeScript's deprecated `module <identifier>` syntax (namespace imports) in `@babel/types` and related packages.fixMigrate 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. affects: >=8.0.0-beta.4
breakingFor 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.fixUpgrade your project's TypeScript version to 4.0 or newer to ensure compatibility with `@babel/types` v8 type definitions.
affects: >=8.0.0-alpha.16
gotchaBabel 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.fixAlways 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. affects: >=8.0.0-rc.2
gotchaUsing 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.fixAlways 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`).
affects: All versions
Errors
Common errors & fixes
TypeError: t.someBuilder is not a function
Attempting to use `babel-types` builder or checker methods after incorrectly importing the package, typically with a default import instead of a namespace import.
fixUse 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'
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.
fixConsult 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)
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).
fixReview 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.
Audit
Dependencies
@babel/helper-string-parserrequiredInternal utility for parsing string literals within AST nodes.
@babel/helper-validator-identifierrequiredInternal utility for validating identifiers according to ECMAScript and Unicode specifications.