Parser Configuration

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

Capabilities

Esprima Parser (Default)

Default JavaScript parser supporting ECMAScript syntax.

// Usage: Use by default or explicitly
const ast = parse(source); // Uses esprima by default
const ast = parse(source, {
  parser: require("recast/parsers/esprima")
});

Import Path: recast/parsers/esprima

Supported Features:

• Standard ECMAScript syntax
• JSX support (when jsx option enabled)
• Module and script parsing modes
• Comment and token tracking

TypeScript Parser

TypeScript parser using Babel parser with TypeScript plugin.

// Usage: Explicitly specify TypeScript parser
const ast = parse(source, {
  parser: require("recast/parsers/typescript")
});

Import Path: recast/parsers/typescript

Prerequisites: Requires @babel/parser to be installed: npm install @babel/parser

Supported Features:

• Full TypeScript syntax support
• Type annotations and declarations
• Generics and interfaces
• Decorators and metadata

Usage Example:

import { parse, print } from "recast";

const tsCode = `
interface User {
  name: string;
  age: number;
}

const user: User = { name: "Alice", age: 30 };
`;

const ast = parse(tsCode, {
  parser: require("recast/parsers/typescript")
});

const result = print(ast);

Babel Parser

Modern JavaScript parser supporting latest ECMAScript features.

// Usage: Use Babel parser for modern JavaScript
const ast = parse(source, {
  parser: require("recast/parsers/babel")
});

Import Path: recast/parsers/babel

Prerequisites: Requires @babel/parser to be installed: npm install @babel/parser

Supported Features:

• Latest ECMAScript proposals
• JSX and Flow syntax
• Decorator syntax with auto-accessors
• Advanced JavaScript features

Flow Parser

Flow type annotation parser using Babel.

// Usage: Parse Flow annotated JavaScript
const ast = parse(source, {
  parser: require("recast/parsers/flow")
});

Import Path: recast/parsers/flow

Prerequisites: Requires @babel/parser to be installed: npm install @babel/parser

Supported Features:

• Flow type annotations
• JSX support
• Modern JavaScript syntax

Acorn Parser

Alternative JavaScript parser with configurable ECMAScript version support.

// Usage: Use Acorn parser
const ast = parse(source, {
  parser: require("recast/parsers/acorn")
});

Import Path: recast/parsers/acorn

Prerequisites: Requires acorn to be installed: npm install acorn

Supported Features:

• Configurable ECMAScript version (default: ES2017)
• Import/export everywhere
• Hash bang support
• Return outside function support

Babel TypeScript Parser (Alternative)

Alternative TypeScript parser with JSX support using Babel.

// Usage: Parse TypeScript with JSX support
const ast = parse(source, {
  parser: require("recast/parsers/babel-ts")
});

Import Path: recast/parsers/babel-ts

Prerequisites: Requires @babel/parser to be installed: npm install @babel/parser

Differences from typescript parser:

• Includes JSX plugin by default
• Uses same underlying Babel parser as other Babel-based parsers

Babylon Parser (Legacy)

Legacy alias for the Babel parser.

// Usage: Legacy Babylon parser (same as babel parser)
const ast = parse(source, {
  parser: require("recast/parsers/babylon")
});

Import Path: recast/parsers/babylon

Note: This is a legacy alias that exports the same functionality as the babel parser. Use the babel parser directly for new projects.

Custom Parser Configuration

Basic Custom Parser

Create custom parser configurations for specific needs.

/**
 * Custom parser object interface
 */
interface CustomParser {
  parse(source: string): any;
}

Usage Example:

import { parse } from "recast";

const customParser = {
  parse(source: string) {
    return require("acorn").parse(source, {
      ecmaVersion: 2020,
      sourceType: "module",
      // custom options
    });
  }
};

const ast = parse(source, {
  parser: customParser
});

Advanced Parser Options

Pass additional options to preconfigured parsers.

Usage Example with TypeScript:

import { parse } from "recast";
import getBabelOptions from "recast/parsers/_babel_options";

const customTypeScriptParser = {
  parse(source: string) {
    const babelOptions = getBabelOptions();
    babelOptions.plugins.push("typescript", "decorators-legacy");
    return require("@babel/parser").parse(source, babelOptions);
  }
};

const ast = parse(source, {
  parser: customTypeScriptParser
});

Parser Selection Guidelines

When to Use Each Parser

Esprima (Default):

• Standard JavaScript projects
• When no special syntax features needed
• Maximum compatibility and stability

TypeScript Parser:

• TypeScript projects with type annotations
• When preserving type information in transformations
• Interface and type declaration processing

Babel Parser:

• Modern JavaScript with latest proposals
• When using experimental ECMAScript features
• React projects with advanced JSX patterns

Flow Parser:

• Projects using Flow type checking
• When preserving Flow annotations is important

Acorn Parser:

• When you need specific ECMAScript version control
• Alternative to Esprima with different parsing behavior
• Projects requiring hash bang or special module handling

Important Notes

1. Shadow Copy Preservation: Always use recast.parse() rather than parsing directly with the underlying parser to maintain the shadow copy system that enables format preservation.

2. Babel Plugin Dependencies: Babel-based parsers (typescript, flow, babel) require @babel/parser to be installed separately.

3. Parser Consistency: Use the same parser for parsing and any subsequent operations to ensure AST compatibility.

4. Source Map Support: All parsers support source map generation when used through recast's parse function.