How to use Recast with TypeScript code?

Recast provides a preconfigured TypeScript parser. First, install @babel/parser via npm, then use require('recast/parsers/typescript') in the parse options. This allows parsing and transforming TypeScript while preserving formatting and generating source maps.

Recast vs Babel for transforming JavaScript?

Recast excels at format-preserving AST manipulations with automatic source maps, ideal for codemods and linters. Babel is a full compiler with a plugin ecosystem for broader transformations; use Recast for precise, style-aware changes and Babel for compilation pipelines.

Does Recast keep comments when modifying code?

Yes, Recast preserves comments and formatting for unmodified parts of the AST. In the README example, the comment '// Weird formatting, huh?' is retained after transforming the function, as long as the surrounding nodes aren't altered.

How to generate source maps with Recast?

Source maps are generated automatically by specifying sourceFileName in parse options and sourceMapName in print options. The result object includes a .map property with a JSON source map that tracks changes at the character level for debugging.

What parsers does Recast support out of the box?

Recast supports Esprima by default, but can be configured with parsers like Acorn, TypeScript, Flow, and Babel. However, for parsers other than Esprima, you must install the corresponding npm packages separately, as noted in the README.

Can Recast handle modern JavaScript features like async/await?

Yes, by using a parser that supports modern syntax, such as Babel or Acorn. Configure the parser option in recast.parse to ensure compatibility with features like async/await, JSX, or decorators, depending on the parser's capabilities.

Recast — JavaScript Syntax Tree Transformer

What is Recast?

Recast is a JavaScript syntax tree transformer and pretty-printer that enables code manipulation while preserving original formatting. It parses JavaScript code into an abstract syntax tree (AST), allows developers to modify the AST, and reprints it with minimal changes to unmodified parts, maintaining code style and automatically generating source maps.

Target Audience

JavaScript and TypeScript developers building code transformation tools, such as codemods, linters, formatters, or compilers, who need to manipulate source code while preserving its original formatting and generating accurate source maps.

Value Proposition

Developers choose Recast over alternatives because it reprints only modified parts of the syntax tree, preserving formatting for unmodified code, and automatically generates high-resolution source maps. Its parser-agnostic design supports multiple parsers like Esprima, Acorn, TypeScript, Flow, and Babel, offering flexibility for different syntax needs.

JavaScript syntax tree transformer, nondestructive pretty-printer, and automatic source map generator

Use Cases

Best For

Writing codemods that refactor code while maintaining existing formatting and comments.
Building custom linters or formatters that need to analyze and modify JavaScript or TypeScript code with minimal style disruption.
Creating source code transformation tools that require accurate source map generation for debugging.
Experimenting with AST manipulations in a safe, reversible way using version control to revert changes.
Integrating multiple parsers (e.g., Babel, TypeScript) into a single code processing pipeline without losing original formatting.
Developing educational or analysis tools that visualize code changes by comparing original and modified syntax trees.

Not Ideal For

Projects performing simple text replacements or regex-based edits where AST parsing is unnecessary overhead
Teams enforcing a strict, uniform code style across the entire codebase, as Recast's fallback to generic formatting can introduce inconsistencies
Environments with strict dependency constraints, since using parsers like Babel or TypeScript requires additional npm package installations

Pros & Cons

Pros

Formatting Preservation

Reprints only modified AST nodes, keeping original formatting for unmodified code, as shown in the example where comments and indentation are retained after transforming a function declaration.

Automatic Source Maps

Generates high-resolution source maps automatically during printing, enabling precise debugging by tracking character-level changes between original and generated code without manual configuration.

Parser Agnostic Design

Supports multiple parsers including Esprima, Acorn, TypeScript, Flow, and Babel, allowing flexibility to handle different JavaScript syntaxes and extensions through configurable parse options.

AST Type Safety

Provides builders and type-checkers from the ast-types module for constructing and validating AST nodes, ensuring manipulations adhere to the Mozilla Parser API and reducing errors.

Cons

External Parser Dependencies

Using parsers other than the default Esprima requires installing separate npm packages (e.g., @babel/parser), adding setup complexity and increasing project dependency management overhead.

Large Source Map Files

Creates character-by-character source maps that do not include identifier names, resulting in larger file sizes compared to token-based maps, which can impact debugging performance in browsers.

Inconsistent Formatting Fallback

When unable to preserve original formatting, Recast defaults to a generic pretty printer, potentially introducing stylistic inconsistencies in the output code, as mentioned in the fallback mechanism.

What is Recast?

Target Audience

Value Proposition

Use Cases

Best For

Writing codemods that refactor code while maintaining existing formatting and comments.
Building custom linters or formatters that need to analyze and modify JavaScript or TypeScript code with minimal style disruption.
Creating source code transformation tools that require accurate source map generation for debugging.
Experimenting with AST manipulations in a safe, reversible way using version control to revert changes.
Integrating multiple parsers (e.g., Babel, TypeScript) into a single code processing pipeline without losing original formatting.
Developing educational or analysis tools that visualize code changes by comparing original and modified syntax trees.

Not Ideal For

Projects performing simple text replacements or regex-based edits where AST parsing is unnecessary overhead
Teams enforcing a strict, uniform code style across the entire codebase, as Recast's fallback to generic formatting can introduce inconsistencies
Environments with strict dependency constraints, since using parsers like Babel or TypeScript requires additional npm package installations

Pros & Cons

Pros

Formatting Preservation

Reprints only modified AST nodes, keeping original formatting for unmodified code, as shown in the example where comments and indentation are retained after transforming a function declaration.

Automatic Source Maps

Generates high-resolution source maps automatically during printing, enabling precise debugging by tracking character-level changes between original and generated code without manual configuration.

Parser Agnostic Design

Supports multiple parsers including Esprima, Acorn, TypeScript, Flow, and Babel, allowing flexibility to handle different JavaScript syntaxes and extensions through configurable parse options.

AST Type Safety

Provides builders and type-checkers from the ast-types module for constructing and validating AST nodes, ensuring manipulations adhere to the Mozilla Parser API and reducing errors.

Cons

External Parser Dependencies

Using parsers other than the default Esprima requires installing separate npm packages (e.g., @babel/parser), adding setup complexity and increasing project dependency management overhead.

Large Source Map Files

Creates character-by-character source maps that do not include identifier names, resulting in larger file sizes compared to token-based maps, which can impact debugging performance in browsers.

Inconsistent Formatting Fallback

When unable to preserve original formatting, Recast defaults to a generic pretty printer, potentially introducing stylistic inconsistencies in the output code, as mentioned in the fallback mechanism.

Recast

What is Recast?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Recast

What is Recast?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?