0
# Parser Configuration
1

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

4
## Capabilities
5

6
### Esprima Parser (Default)
7

8
Default JavaScript parser supporting ECMAScript syntax.
9

10
```typescript { .api }
11
// Usage: Use by default or explicitly
12
const ast = parse(source); // Uses esprima by default
13
const ast = parse(source, {
14
  parser: require("recast/parsers/esprima")
15
});
16
```
17

18
**Import Path:** `recast/parsers/esprima`
19

20
**Supported Features:**
21
- Standard ECMAScript syntax
22
- JSX support (when jsx option enabled)
23
- Module and script parsing modes
24
- Comment and token tracking
25

26
### TypeScript Parser
27

28
TypeScript parser using Babel parser with TypeScript plugin.
29

30
```typescript { .api }
31
// Usage: Explicitly specify TypeScript parser
32
const ast = parse(source, {
33
  parser: require("recast/parsers/typescript")
34
});
35
```
36

37
**Import Path:** `recast/parsers/typescript`
38

39
**Prerequisites:** Requires `@babel/parser` to be installed: `npm install @babel/parser`
40

41
**Supported Features:**
42
- Full TypeScript syntax support
43
- Type annotations and declarations
44
- Generics and interfaces
45
- Decorators and metadata
46

47
**Usage Example:**
48

49
```typescript
50
import { parse, print } from "recast";
51

52
const tsCode = `
53
interface User {
54
  name: string;
55
  age: number;
56
}
57

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

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

65
const result = print(ast);
66
```
67

68
### Babel Parser
69

70
Modern JavaScript parser supporting latest ECMAScript features.
71

72
```typescript { .api }
73
// Usage: Use Babel parser for modern JavaScript
74
const ast = parse(source, {
75
  parser: require("recast/parsers/babel")
76
});
77
```
78

79
**Import Path:** `recast/parsers/babel`
80

81
**Prerequisites:** Requires `@babel/parser` to be installed: `npm install @babel/parser`
82

83
**Supported Features:**
84
- Latest ECMAScript proposals
85
- JSX and Flow syntax
86
- Decorator syntax with auto-accessors
87
- Advanced JavaScript features
88

89
### Flow Parser
90

91
Flow type annotation parser using Babel.
92

93
```typescript { .api }
94
// Usage: Parse Flow annotated JavaScript
95
const ast = parse(source, {
96
  parser: require("recast/parsers/flow")
97
});
98
```
99

100
**Import Path:** `recast/parsers/flow`
101

102
**Prerequisites:** Requires `@babel/parser` to be installed: `npm install @babel/parser`
103

104
**Supported Features:**
105
- Flow type annotations
106
- JSX support
107
- Modern JavaScript syntax
108

109
### Acorn Parser
110

111
Alternative JavaScript parser with configurable ECMAScript version support.
112

113
```typescript { .api }
114
// Usage: Use Acorn parser
115
const ast = parse(source, {
116
  parser: require("recast/parsers/acorn")
117
});
118
```
119

120
**Import Path:** `recast/parsers/acorn`
121

122
**Prerequisites:** Requires `acorn` to be installed: `npm install acorn`
123

124
**Supported Features:**
125
- Configurable ECMAScript version (default: ES2017)
126
- Import/export everywhere
127
- Hash bang support
128
- Return outside function support
129

130
### Babel TypeScript Parser (Alternative)
131

132
Alternative TypeScript parser with JSX support using Babel.
133

134
```typescript { .api }
135
// Usage: Parse TypeScript with JSX support
136
const ast = parse(source, {
137
  parser: require("recast/parsers/babel-ts")
138
});
139
```
140

141
**Import Path:** `recast/parsers/babel-ts`
142

143
**Prerequisites:** Requires `@babel/parser` to be installed: `npm install @babel/parser`
144

145
**Differences from `typescript` parser:**
146
- Includes JSX plugin by default
147
- Uses same underlying Babel parser as other Babel-based parsers
148

149
### Babylon Parser (Legacy)
150

151
Legacy alias for the Babel parser.
152

153
```typescript { .api }
154
// Usage: Legacy Babylon parser (same as babel parser)
155
const ast = parse(source, {
156
  parser: require("recast/parsers/babylon")
157
});
158
```
159

160
**Import Path:** `recast/parsers/babylon`
161

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

164
## Custom Parser Configuration
165

166
### Basic Custom Parser
167

168
Create custom parser configurations for specific needs.
169

170
```typescript { .api }
171
/**
172
 * Custom parser object interface
173
 */
174
interface CustomParser {
175
  parse(source: string): any;
176
}
177
```
178

179
**Usage Example:**
180

181
```typescript
182
import { parse } from "recast";
183

184
const customParser = {
185
  parse(source: string) {
186
    return require("acorn").parse(source, {
187
      ecmaVersion: 2020,
188
      sourceType: "module",
189
      // custom options
190
    });
191
  }
192
};
193

194
const ast = parse(source, {
195
  parser: customParser
196
});
197
```
198

199
### Advanced Parser Options
200

201
Pass additional options to preconfigured parsers.
202

203
**Usage Example with TypeScript:**
204

205
```typescript
206
import { parse } from "recast";
207
import getBabelOptions from "recast/parsers/_babel_options";
208

209
const customTypeScriptParser = {
210
  parse(source: string) {
211
    const babelOptions = getBabelOptions();
212
    babelOptions.plugins.push("typescript", "decorators-legacy");
213
    return require("@babel/parser").parse(source, babelOptions);
214
  }
215
};
216

217
const ast = parse(source, {
218
  parser: customTypeScriptParser
219
});
220
```
221

222
## Parser Selection Guidelines
223

224
### When to Use Each Parser
225

226
**Esprima (Default):**
227
- Standard JavaScript projects
228
- When no special syntax features needed
229
- Maximum compatibility and stability
230

231
**TypeScript Parser:**
232
- TypeScript projects with type annotations
233
- When preserving type information in transformations
234
- Interface and type declaration processing
235

236
**Babel Parser:**
237
- Modern JavaScript with latest proposals
238
- When using experimental ECMAScript features
239
- React projects with advanced JSX patterns
240

241
**Flow Parser:**
242
- Projects using Flow type checking
243
- When preserving Flow annotations is important
244

245
**Acorn Parser:**
246
- When you need specific ECMAScript version control
247
- Alternative to Esprima with different parsing behavior
248
- Projects requiring hash bang or special module handling
249

250
### Important Notes
251

252
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.
253

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

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

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