0
# Parser Configuration
1

2
Parser configuration for JavaScript and TypeScript syntax support. These types define comprehensive parsing options for different language features, syntax variants, and experimental proposals.
3

4
## Capabilities
5

6
### Main Parser Configuration
7

8
Core parsing configuration types for JavaScript and TypeScript.
9

10
```typescript { .api }
11
/**
12
 * Parse options combining parser config with additional settings
13
 */
14
type ParseOptions = ParserConfig & {
15
  /** Parse and preserve comments */
16
  comments?: boolean;
17
  /** Parse as script instead of module */
18
  script?: boolean;
19
  /** ECMAScript target version (defaults to es3) */
20
  target?: JscTarget;
21
};
22

23
/**
24
 * Parser configuration union for JavaScript or TypeScript
25
 */
26
type ParserConfig = TsParserConfig | EsParserConfig;
27

28
type JscTarget = 
29
  | "es3" | "es5" | "es2015" | "es2016" | "es2017" 
30
  | "es2018" | "es2019" | "es2020" | "es2021" 
31
  | "es2022" | "es2023" | "es2024" | "esnext";
32
```
33

34
### TypeScript Parser Configuration
35

36
Parser settings specifically for TypeScript syntax and features.
37

38
```typescript { .api }
39
/**
40
 * TypeScript parser configuration
41
 */
42
interface TsParserConfig {
43
  /** Parser syntax identifier */
44
  syntax: "typescript";
45
  /** Enable TSX/JSX parsing in TypeScript files */
46
  tsx?: boolean;
47
  /** Enable decorator parsing */
48
  decorators?: boolean;
49
  /** @deprecated Always true - dynamic imports are in ES spec */
50
  dynamicImport?: boolean;
51
}
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import type { TsParserConfig } from "@swc/types";
58

59
// Basic TypeScript parsing
60
const basicTs: TsParserConfig = {
61
  syntax: "typescript"
62
};
63

64
// TypeScript with JSX support
65
const tsxConfig: TsParserConfig = {
66
  syntax: "typescript",
67
  tsx: true
68
};
69

70
// TypeScript with decorators
71
const decoratorTs: TsParserConfig = {
72
  syntax: "typescript",
73
  decorators: true
74
};
75

76
// Full TypeScript feature support
77
const fullTs: TsParserConfig = {
78
  syntax: "typescript",
79
  tsx: true,
80
  decorators: true
81
};
82
```
83

84
### ECMAScript Parser Configuration
85

86
Comprehensive JavaScript parser configuration with extensive feature flags.
87

88
```typescript { .api }
89
/**
90
 * ECMAScript/JavaScript parser configuration
91
 */
92
interface EsParserConfig {
93
  /** Parser syntax identifier */
94
  syntax: "ecmascript";
95
  /** Enable JSX parsing */
96
  jsx?: boolean;
97
  /** Enable decorator parsing */
98
  decorators?: boolean;
99
  /** Decorators before export keyword */
100
  decoratorsBeforeExport?: boolean;
101
  /** Enable function bind operator */
102
  functionBind?: boolean;
103
  /** Enable export default from syntax */
104
  exportDefaultFrom?: boolean;
105
  /** Allow super outside method context */
106
  allowSuperOutsideMethod?: boolean;
107
  /** Allow return outside function context */
108
  allowReturnOutsideFunction?: boolean;
109
  /** Enable auto accessors */
110
  autoAccessors?: boolean;
111
  /** Enable explicit resource management */
112
  explicitResourceManagement?: boolean;
113
  
114
  // Deprecated features (always enabled in modern ES)
115
  /** @deprecated Always true - numeric separators are in ES spec */
116
  numericSeparator?: boolean;
117
  /** @deprecated Always true - class private properties are in ES spec */
118
  classPrivateProperty?: boolean;
119
  /** @deprecated Always true - private methods are in ES spec */
120
  privateMethod?: boolean;
121
  /** @deprecated Always true - class properties are in ES spec */
122
  classProperty?: boolean;
123
  /** @deprecated Always true - export namespace from is in ES spec */
124
  exportNamespaceFrom?: boolean;
125
  /** @deprecated Always true - dynamic imports are in ES spec */
126
  dynamicImport?: boolean;
127
  /** @deprecated Always true - nullish coalescing is in ES spec */
128
  nullishCoalescing?: boolean;
129
  /** @deprecated Always true - optional chaining is in ES spec */
130
  optionalChaining?: boolean;
131
  /** @deprecated Always true - import.meta is in ES spec */
132
  importMeta?: boolean;
133
  /** @deprecated Always true - top level await is in ES spec */
134
  topLevelAwait?: boolean;
135
  /** @deprecated Use importAttributes instead */
136
  importAssertions?: boolean;
137
  /** @deprecated Always true in SWC */
138
  importAttributes?: boolean;
139
}
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
import type { EsParserConfig } from "@swc/types";
146

147
// Basic JavaScript parsing
148
const basicJs: EsParserConfig = {
149
  syntax: "ecmascript"
150
};
151

152
// JavaScript with JSX
153
const jsxConfig: EsParserConfig = {
154
  syntax: "ecmascript",
155
  jsx: true
156
};
157

158
// Modern JavaScript with experimental features
159
const modernJs: EsParserConfig = {
160
  syntax: "ecmascript",
161
  jsx: true,
162
  decorators: true,
163
  decoratorsBeforeExport: true,
164
  functionBind: true,
165
  exportDefaultFrom: true,
166
  autoAccessors: true,
167
  explicitResourceManagement: true
168
};
169

170
// Flexible JavaScript parsing
171
const flexibleJs: EsParserConfig = {
172
  syntax: "ecmascript",
173
  allowSuperOutsideMethod: true,
174
  allowReturnOutsideFunction: true
175
};
176

177
// React-focused configuration
178
const reactConfig: EsParserConfig = {
179
  syntax: "ecmascript",
180
  jsx: true,
181
  decorators: true, // For class components with decorators
182
  decoratorsBeforeExport: true
183
};
184
```
185

186
### Complete Parser Examples
187

188
Real-world parser configuration examples for different use cases.
189

190
```typescript
191
import type { ParseOptions, ParserConfig, JscTarget } from "@swc/types";
192

193
// Next.js TypeScript configuration
194
const nextjsTs: ParseOptions = {
195
  syntax: "typescript",
196
  tsx: true,
197
  decorators: true,
198
  comments: true,
199
  target: "es2020"
200
};
201

202
// React library development
203
const reactLib: ParseOptions = {
204
  syntax: "typescript", 
205
  tsx: true,
206
  decorators: true,
207
  comments: false, // Strip comments for production
208
  target: "es2018"
209
};
210

211
// Legacy browser support
212
const legacyJs: ParseOptions = {
213
  syntax: "ecmascript",
214
  jsx: true,
215
  target: "es5"
216
};
217

218
// Modern Node.js application
219
const nodeApp: ParseOptions = {
220
  syntax: "typescript",
221
  decorators: true,
222
  comments: true,
223
  target: "es2022"
224
};
225

226
// Experimental features testing
227
const experimental: ParseOptions = {
228
  syntax: "ecmascript",
229
  jsx: true,
230
  decorators: true,
231
  decoratorsBeforeExport: true,
232
  functionBind: true,
233
  exportDefaultFrom: true,
234
  autoAccessors: true,
235
  explicitResourceManagement: true,
236
  allowSuperOutsideMethod: true,
237
  allowReturnOutsideFunction: true,
238
  target: "esnext"
239
};
240

241
// Strict parsing for production
242
const production: ParseOptions = {
243
  syntax: "typescript",
244
  tsx: true,
245
  decorators: false, // Disable experimental features
246
  comments: false,   // Strip comments
247
  target: "es2020"
248
};
249

250
// Development with maximum compatibility
251
const development: ParseOptions = {
252
  syntax: "typescript",
253
  tsx: true,
254
  decorators: true,
255
  comments: true,    // Keep comments for debugging
256
  script: false,     // Parse as module
257
  target: "esnext"   // Support latest features
258
};
259
```
260

261
### Parser Feature Support Matrix
262

263
Overview of which features are supported in different parser configurations:
264

265
**TypeScript Parser (`TsParserConfig`):**
266
- ✅ TypeScript syntax (types, interfaces, generics)
267
- ✅ JSX/TSX (when `tsx: true`)
268
- ✅ Decorators (when `decorators: true`)
269
- ✅ All modern ES features
270
- ✅ TypeScript-specific imports/exports
271

272
**ECMAScript Parser (`EsParserConfig`):**
273
- ✅ Modern JavaScript syntax
274
- ✅ JSX (when `jsx: true`)
275
- ✅ Decorators (when `decorators: true`)
276
- ✅ Experimental proposals (with feature flags)
277
- ❌ TypeScript-specific syntax
278

279
**Target Version Impact:**
280
- `es3`/`es5`: Conservative parsing, fewer modern features
281
- `es2015`+: Modern JavaScript features enabled
282
- `esnext`: All experimental features available
283

284
**Best Practices:**
285

286
1. **Use TypeScript parser for `.ts/.tsx` files** even if not using all TypeScript features
287
2. **Enable `comments: true` in development** for better debugging experience
288
3. **Match target to your deployment environment** for optimal compatibility
289
4. **Enable experimental features cautiously** - they may change or be removed
290
5. **Use `script: true` only for non-module code** (rare in modern development)