recast

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

weekly downloads19.3M

versionv0.23.11

licenseMIT

categorytoolchain

astrewritingrefactoringcodegensyntaxtransformationparsingpretty-printing

Overview

Recast is a JavaScript syntax tree transformer that parses code into an Abstract Syntax Tree (AST), allows programmatic modifications, and reprints it back to source code while preserving the original formatting. Unlike traditional pretty-printers that reformat entire files, Recast only reprints the portions of code you've actually modified, leaving unchanged code exactly as the developer originally wrote it.

The library solves a critical problem in automated refactoring: maintaining code style and formatting during large-scale transformations. When you need to rename thousands of function calls, modernize syntax patterns, or apply complex refactoring across a codebase, manual editing becomes impractical. Recast enables these transformations programmatically while respecting existing code conventions, preserving comments, and maintaining git diff readability.

With over 19 million weekly downloads, Recast powers numerous developer tools including code migration utilities, linters, bundlers, and automated refactoring systems. It's built on a compatible parser interface similar to esprima, supports multiple JavaScript parsers (including Babel and Acorn), and generates source maps automatically. The library is particularly valuable for teams maintaining large codebases who need to apply systematic changes without disrupting established formatting conventions.

Recast achieves formatting preservation through a shadow AST mechanism: it maintains references to original nodes via an .original property, allowing it to detect which nodes were modified during traversal. Only modified subtrees get reprinted using the library's pretty-printer, while unmodified nodes retain their original source representation character-for-character.

Quick Start

typescript

const recast = require('recast');
const { namedTypes: n, builders: b } = recast.types;

const sourceCode = `
function calculatePrice(items) {
  var total = 0;
  for (var i = 0; i < items.length; i++) {
    total += items[i].price;
  }
  return total;
}
`;

// Parse code into AST
const ast = recast.parse(sourceCode);

// Transform var declarations to const/let
recast.visit(ast, {
  visitVariableDeclaration(path) {
    const node = path.node;
    if (node.kind === 'var') {
      // Check if variable is reassigned
      const isReassigned = path.scope.lookup(node.declarations[0].id.name)
        ?.getBindings()[node.declarations[0].id.name]
        ?.some(binding => binding.parentPath.value.type === 'AssignmentExpression');
      
      node.kind = isReassigned ? 'let' : 'const';
    }
    this.traverse(path);
  },
  
  // Transform for loop to forEach
  visitForStatement(path) {
    const node = path.node;
    // Simple pattern match for array iteration
    if (n.MemberExpression.check(node.test?.right) && 
        node.test.right.property.name === 'length') {
      
      const arrayName = node.test.right.object.name;
      const body = node.body.body;
      
      // Create forEach call
      const forEachCall = b.expressionStatement(
        b.callExpression(
          b.memberExpression(
            b.identifier(arrayName),
            b.identifier('forEach'),
            false
          ),
          [b.arrowFunctionExpression(
            [b.identifier('item')],
            b.blockStatement(body)
          )]
        )
      );
      
      path.replace(forEachCall);
    }
    return false;
  }
});

// Print only modified code, preserving original formatting elsewhere
const transformedCode = recast.print(ast, { tabWidth: 2 }).code;

console.log(transformedCode);
// Output maintains original structure but with modernized syntax

Use Cases

Large-scale codebase refactoring: When migrating from CommonJS to ES modules across hundreds of files, Recast can automatically transform require() calls to import statements while preserving each file's unique formatting style, comment placement, and whitespace conventions.

API migration automation: When a library releases a breaking version with renamed methods, Recast enables writing a codemod script that finds all usages of old API calls and transforms them to the new syntax, making upgrades across large projects manageable without manual find-and-replace.

Code modernization tooling: Building tools that upgrade legacy code patterns (converting var to const/let, transforming callbacks to async/await, updating deprecated syntax) while maintaining the developer's original code style and avoiding unnecessary diffs in version control.

Custom linting with auto-fix: Creating specialized lint rules that not only detect issues but automatically fix them by modifying the AST, such as enforcing consistent error handling patterns or standardizing import ordering across a monorepo.

Template-based code generation: Generating boilerplate code from templates or schemas where you parse existing code files, inject new function definitions or class methods, and write back the modified file without reformatting the entire document.

Pros & Cons

Pros

+Preserves original code formatting for clean git diffs, only reprinting modified AST nodes instead of reformatting entire files
+Parser-agnostic design supports multiple JavaScript parsers (Babel, Acorn, Esprima) allowing flexibility for different syntax requirements
+Automatic source map generation tracks transformations from original to modified code, essential for debugging transformed output
+Comprehensive AST manipulation API with builders and type validators simplifies constructing and validating complex code transformations
+Battle-tested in production with 19M+ weekly downloads, powering major tooling in the JavaScript ecosystem

Cons

−Steep learning curve requires understanding AST structure and node types before writing effective transformations
−Performance overhead on very large files due to maintaining shadow AST copies and original source references
−Limited documentation for advanced use cases and edge cases, often requiring source code inspection to understand behavior
−Format preservation can produce inconsistent results when mixing heavily modified and unmodified code sections
−Debugging transformed code can be challenging when AST modifications don't produce expected output syntax

Alternatives

jscodeshiftv17.3.0

A toolkit for JavaScript codemods

toolchaincodemodrecast

5.6M / week

prettierv3.8.1

Prettier is an opinionated code formatter

toolchain

68.2M / week

Install

bash

npm install recast

bash

pnpm add recast

bash

bun add recast

Overview

Quick Start

typescript

const recast = require('recast');
const { namedTypes: n, builders: b } = recast.types;

const sourceCode = `
function calculatePrice(items) {
  var total = 0;
  for (var i = 0; i < items.length; i++) {
    total += items[i].price;
  }
  return total;
}
`;

// Parse code into AST
const ast = recast.parse(sourceCode);

// Transform var declarations to const/let
recast.visit(ast, {
  visitVariableDeclaration(path) {
    const node = path.node;
    if (node.kind === 'var') {
      // Check if variable is reassigned
      const isReassigned = path.scope.lookup(node.declarations[0].id.name)
        ?.getBindings()[node.declarations[0].id.name]
        ?.some(binding => binding.parentPath.value.type === 'AssignmentExpression');
      
      node.kind = isReassigned ? 'let' : 'const';
    }
    this.traverse(path);
  },
  
  // Transform for loop to forEach
  visitForStatement(path) {
    const node = path.node;
    // Simple pattern match for array iteration
    if (n.MemberExpression.check(node.test?.right) && 
        node.test.right.property.name === 'length') {
      
      const arrayName = node.test.right.object.name;
      const body = node.body.body;
      
      // Create forEach call
      const forEachCall = b.expressionStatement(
        b.callExpression(
          b.memberExpression(
            b.identifier(arrayName),
            b.identifier('forEach'),
            false
          ),
          [b.arrowFunctionExpression(
            [b.identifier('item')],
            b.blockStatement(body)
          )]
        )
      );
      
      path.replace(forEachCall);
    }
    return false;
  }
});

// Print only modified code, preserving original formatting elsewhere
const transformedCode = recast.print(ast, { tabWidth: 2 }).code;

console.log(transformedCode);
// Output maintains original structure but with modernized syntax

Use Cases

Pros & Cons

Pros

+Preserves original code formatting for clean git diffs, only reprinting modified AST nodes instead of reformatting entire files
+Parser-agnostic design supports multiple JavaScript parsers (Babel, Acorn, Esprima) allowing flexibility for different syntax requirements
+Automatic source map generation tracks transformations from original to modified code, essential for debugging transformed output
+Comprehensive AST manipulation API with builders and type validators simplifies constructing and validating complex code transformations
+Battle-tested in production with 19M+ weekly downloads, powering major tooling in the JavaScript ecosystem

Cons

−Steep learning curve requires understanding AST structure and node types before writing effective transformations
−Performance overhead on very large files due to maintaining shadow AST copies and original source references
−Limited documentation for advanced use cases and edge cases, often requiring source code inspection to understand behavior
−Format preservation can produce inconsistent results when mixing heavily modified and unmodified code sections
−Debugging transformed code can be challenging when AST modifications don't produce expected output syntax