0
# Recast
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: recast
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install recast`
10

11
## Core Imports
12

13
```typescript
14
import { parse, print, prettyPrint, types, visit, run } from "recast";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { parse, print, prettyPrint, types, visit, run } = require("recast");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { parse, print, types } from "recast";
27

28
// Parse source code into an AST
29
const code = `
30
function add(a, b) {
31
  return a + b;
32
}`;
33

34
const ast = parse(code);
35

36
// Transform the AST using ast-types builders
37
const b = types.builders;
38
ast.program.body[0] = b.variableDeclaration("const", [
39
  b.variableDeclarator(
40
    b.identifier("add"),
41
    b.functionExpression(null, ast.program.body[0].params, ast.program.body[0].body)
42
  )
43
]);
44

45
// Print back to source code, preserving original formatting where unchanged
46
const result = print(ast);
47
console.log(result.code);
48
```
49

50
## Architecture
51

52
Recast is built around several key components:
53

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

60
## Capabilities
61

62
### Core Parsing and Printing
63

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

66
```typescript { .api }
67
function parse(source: string, options?: Options): types.ASTNode;
68
function print(node: types.ASTNode, options?: Options): PrintResultType;
69
function prettyPrint(node: types.ASTNode, options?: Options): PrintResultType;
70
```
71

72
[Core Operations](./core-operations.md)
73

74
### Parser Configuration
75

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

78
```typescript { .api }
79
interface Options {
80
  parser?: any;
81
  tabWidth?: number;
82
  useTabs?: boolean;
83
  reuseWhitespace?: boolean;
84
  sourceFileName?: string;
85
  sourceMapName?: string;
86
  // ... many more options
87
}
88
```
89

90
[Parser Configuration](./parser-configuration.md)
91

92
### AST Manipulation
93

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

96
```typescript { .api }
97
function visit(ast: types.ASTNode, visitor: Visitor): types.ASTNode;
98

99
interface Visitor {
100
  [key: string]: (path: NodePath) => any;
101
}
102
```
103

104
[AST Manipulation](./ast-manipulation.md)
105

106
### Source Maps
107

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

110
```typescript { .api }
111
interface PrintResultType {
112
  code: string;
113
  map?: SourceMap;
114
  toString(): string;
115
}
116
```
117

118
[Source Maps](./source-maps.md)
119

120
### Command Line Interface
121

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

124
```typescript { .api }
125
function run(transformer: Transformer, options?: RunOptions): void;
126

127
interface Transformer {
128
  (ast: types.ASTNode, callback: (ast: types.ASTNode) => void): void;
129
}
130
```
131

132
[CLI Interface](./cli-interface.md)