{"id":15084,"library":"babel-types","title":"Babel AST Utilities","description":"Babel Types (`@babel/types`) is a foundational package within the Babel ecosystem, providing a comprehensive set of utility methods for creating, manipulating, and validating Abstract Syntax Tree (AST) nodes. It adheres to the ESTree specification and Babel's extended AST format, making it essential for anyone writing custom Babel plugins, codemods, or performing static analysis on JavaScript code. The current stable major version is `v7.x`, with the latest being `v7.29.2`, while `v8.x` is in release candidate phase. As part of the Babel monorepo, it follows Babel's frequent release cycle for patches and minors, with major versions introducing significant breaking changes. Its key differentiator is its tight integration and compatibility with Babel's parser (`@babel/parser`) and traverser (`@babel/traverse`), providing canonical builders (e.g., `t.identifier()`), type checkers (e.g., `t.isIdentifier()`), and assertion functions (e.g., `t.assertIdentifier()`) for programmatic AST interaction.","status":"active","version":"6.26.0","language":"javascript","source_language":"en","source_url":"https://github.com/babel/babel/tree/master/packages/babel-types","tags":["javascript"],"install":[{"cmd":"npm install babel-types","lang":"bash","label":"npm"},{"cmd":"yarn add babel-types","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-types","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal utility for parsing string literals within AST nodes.","package":"@babel/helper-string-parser","optional":false},{"reason":"Internal utility for validating identifiers according to ECMAScript and Unicode specifications.","package":"@babel/helper-validator-identifier","optional":false}],"imports":[{"note":"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.","wrong":"import t from '@babel/types';","symbol":"t","correct":"import * as t from '@babel/types';"},{"note":"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.","symbol":"Node","correct":"import type { Node } from '@babel/types';"},{"note":"Specific AST node interfaces can be imported as types for precise TypeScript type hinting, ensuring type safety when working with Babel's AST structures.","symbol":"ArrowFunctionExpression","correct":"import type { ArrowFunctionExpression } from '@babel/types';"}],"quickstart":{"code":"import * as t from '@babel/types';\nimport generate from '@babel/generator';\n\n// Create identifiers for 'a' and 'b'\nconst paramA = t.identifier('a');\nconst paramB = t.identifier('b');\n\n// Create a binary expression 'a + b'\nconst sumExpression = t.binaryExpression('+', paramA, paramB);\n\n// Create a return statement for 'a + b'\nconst returnStatement = t.returnStatement(sumExpression);\n\n// Create a block statement for the function body\nconst functionBody = t.blockStatement([returnStatement]);\n\n// Create an arrow function expression '(...params) => { ...body }'\nconst arrowFunction = t.arrowFunctionExpression(\n  [paramA, paramB], // params\n  functionBody,     // body\n  false             // async\n);\n\n// Create a variable declarator: 'add = (...)'\nconst declarator = t.variableDeclarator(t.identifier('add'), arrowFunction);\n\n// Create a variable declaration: 'const add = (...)'\nconst variableDeclaration = t.variableDeclaration('const', [declarator]);\n\n// Wrap the declaration in a Program node\nconst program = t.program([variableDeclaration]);\n\n// Generate code from the AST (requires @babel/generator)\nconst { code } = generate(program);\nconsole.log(code);\n// Expected output: const add = (a, b) => a + b;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Babel v8 has removed support for TypeScript's deprecated `module <identifier>` syntax (namespace imports) in `@babel/types` and related packages.","severity":"breaking","affected_versions":">=8.0.0-beta.4"},{"fix":"Upgrade your project's TypeScript version to 4.0 or newer to ensure compatibility with `@babel/types` v8 type definitions.","message":"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.","severity":"breaking","affected_versions":">=8.0.0-alpha.16"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=8.0.0-rc.2"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use a namespace import: `import * as t from '@babel/types';` if using ESM, or `const t = require('@babel/types');` if using CommonJS.","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.","error":"TypeError: t.someBuilder is not a function"},{"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.","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.","error":"Error: Unknown node type: 'MyCustomNode'"},{"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.","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).","error":"Invariant Violation: someProperty must be a(n) string (or similar type mismatch)"}],"ecosystem":"npm"}