Recast

Recast is a JavaScript syntax tree transformer, nondestructive pretty-printer, and automatic source map generator. It enables parsing JavaScript/TypeScript code into Abstract Syntax Trees (ASTs), performing transformations while preserving original formatting for unchanged code, and generating high-resolution source maps automatically.

Package Information

• Package Name: recast
• Package Type: npm
• Language: TypeScript
• Installation: npm install recast

Core Imports

import { parse, print, prettyPrint, types, visit, run } from "recast";

For CommonJS:

const { parse, print, prettyPrint, types, visit, run } = require("recast");

Basic Usage

import { parse, print, types } from "recast";

// Parse source code into an AST
const code = `
function add(a, b) {
  return a + b;
}`;

const ast = parse(code);

// Transform the AST using ast-types builders
const b = types.builders;
ast.program.body[0] = b.variableDeclaration("const", [
  b.variableDeclarator(
    b.identifier("add"),
    b.functionExpression(null, ast.program.body[0].params, ast.program.body[0].body)
  )
]);

// Print back to source code, preserving original formatting where unchanged
const result = print(ast);
console.log(result.code);

Architecture

Recast is built around several key components:

• Parser Interface: Unified parsing interface supporting multiple parsers (Esprima, Babel, TypeScript, Flow, Acorn)
• AST Enhancement: Creates shadow copies of AST nodes with .original property references for tracking changes
• Smart Reprinting: Preserves original formatting for unchanged AST nodes while pretty-printing modified portions
• Source Map Generation: Automatic high-resolution source map generation during reprinting
• Type System Integration: Full integration with ast-types for AST manipulation and traversal

Capabilities

Core Parsing and Printing

Essential functions for parsing source code into ASTs and reprinting modified ASTs back to source code.

function parse(source: string, options?: Options): types.ASTNode;
function print(node: types.ASTNode, options?: Options): PrintResultType;
function prettyPrint(node: types.ASTNode, options?: Options): PrintResultType;

Core Operations

Parser Configuration

Preconfigured parsers for different JavaScript dialects and advanced parser configuration options.

interface Options {
  parser?: any;
  tabWidth?: number;
  useTabs?: boolean;
  reuseWhitespace?: boolean;
  sourceFileName?: string;
  sourceMapName?: string;
  // ... many more options
}

Parser Configuration

AST Manipulation

Tools for traversing and modifying Abstract Syntax Trees with type safety.

function visit(ast: types.ASTNode, visitor: Visitor): types.ASTNode;

interface Visitor {
  [key: string]: (path: NodePath) => any;
}

AST Manipulation

Source Maps

Automatic source map generation for tracking original source locations through transformations.

interface PrintResultType {
  code: string;
  map?: SourceMap;
  toString(): string;
}

Source Maps

Command Line Interface

Convenient command-line interface for running transformations on files directly from the shell or within scripts.

function run(transformer: Transformer, options?: RunOptions): void;

interface Transformer {
  (ast: types.ASTNode, callback: (ast: types.ASTNode) => void): void;
}

CLI Interface