0
# Parser Configuration
1

2
Comprehensive configuration interfaces for the TypeScript parser, enabling precise control over parsing behavior, ECMAScript features, TypeScript project integration, and debugging options.
3

4
## Capabilities
5

6
### ParserOptions Interface
7

8
Complete configuration interface for the TypeScript-ESTree parser.
9

10
```typescript { .api }
11
interface ParserOptions {
12
  [additionalProperties: string]: unknown;
13
  
14
  // Cache configuration
15
  cacheLifetime?: {
16
    glob?: CacheDurationSeconds;
17
  };
18

19
  // Core parsing options
20
  debugLevel?: DebugLevel;
21
  ecmaFeatures?: {
22
    [key: string]: unknown;
23
    globalReturn?: boolean | undefined;
24
    jsx?: boolean | undefined;
25
  } | undefined;
26
  ecmaVersion?: EcmaVersion;
27
  sourceType?: SourceType | undefined;
28

29
  // TypeScript-specific options
30
  emitDecoratorMetadata?: boolean;
31
  errorOnTypeScriptSyntacticAndSemanticIssues?: boolean;
32
  errorOnUnknownASTType?: boolean;
33
  experimentalDecorators?: boolean;
34
  extraFileExtensions?: string[];
35
  filePath?: string;
36
  isolatedDeclarations?: boolean;
37
  
38
  // JSDoc and JSX configuration
39
  jsDocParsingMode?: JSDocParsingMode;
40
  jsxFragmentName?: string | null;
41
  jsxPragma?: string | null;
42
  
43
  // Library and program configuration
44
  lib?: Lib[];
45
  programs?: Program[] | null;
46
  
47
  // Project configuration
48
  project?: boolean | string | string[] | null;
49
  projectFolderIgnoreList?: string[];
50
  projectService?: boolean | ProjectServiceOptions;
51
  
52
  // Token and range options
53
  range?: boolean;
54
  tokens?: boolean;
55
  tsconfigRootDir?: string;
56
  
57
  // Warnings
58
  warnOnUnsupportedTypeScriptVersion?: boolean;
59
}
60
```
61

62
### Core Configuration Types
63

64
Type definitions for parser configuration values.
65

66
```typescript { .api }
67
/**
68
 * Debug level configuration for parser output
69
 */
70
type DebugLevel = 
71
  | boolean 
72
  | ('eslint' | 'typescript' | 'typescript-eslint')[];
73

74
/**
75
 * Cache duration specification in seconds
76
 */
77
type CacheDurationSeconds = number | 'Infinity';
78

79
/**
80
 * ECMAScript version specification
81
 */
82
type EcmaVersion =
83
  | 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17
84
  | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | 2026
85
  | 'latest'
86
  | undefined;
87

88
/**
89
 * Source type specification for module resolution
90
 */
91
type SourceType = 'commonjs' | SourceTypeClassic;
92
type SourceTypeClassic = 'module' | 'script';
93

94
/**
95
 * JSDoc parsing mode configuration
96
 */
97
type JSDocParsingMode = 'all' | 'none' | 'type-info';
98
```
99

100
### Project Service Configuration
101

102
Options for configuring the TypeScript project service.
103

104
```typescript { .api }
105
/**
106
 * Granular options to configure the project service
107
 */
108
interface ProjectServiceOptions {
109
  /**
110
   * Globs of files to allow running with the default project compiler options
111
   * despite not being matched by the project service
112
   */
113
  allowDefaultProject?: string[];
114

115
  /**
116
   * Path to a TSConfig to use instead of TypeScript's default project configuration
117
   * @default 'tsconfig.json'
118
   */
119
  defaultProject?: string;
120

121
  /**
122
   * Whether to allow TypeScript plugins as configured in the TSConfig
123
   */
124
  loadTypeScriptPlugins?: boolean;
125

126
  /**
127
   * The maximum number of files allowDefaultProject may match.
128
   * Each file match slows down linting, so if you do need to use this, please
129
   * file an informative issue on typescript-eslint explaining why - so we can
130
   * help you avoid using it!
131
   * @default 8
132
   */
133
  maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING?: number;
134
}
135
```
136

137
**Usage Examples:**
138

139
```typescript
140
import { ParserOptions, DebugLevel, EcmaVersion } from "@typescript-eslint/types";
141

142
// Basic parser configuration
143
const basicConfig: ParserOptions = {
144
  ecmaVersion: 2022,
145
  sourceType: "module",
146
  project: "./tsconfig.json"
147
};
148

149
// Advanced configuration with TypeScript features
150
const advancedConfig: ParserOptions = {
151
  ecmaVersion: "latest",
152
  sourceType: "module",
153
  project: ["./tsconfig.json", "./packages/*/tsconfig.json"],
154
  tsconfigRootDir: __dirname,
155
  
156
  // TypeScript features
157
  experimentalDecorators: true,
158
  emitDecoratorMetadata: true,
159
  isolatedDeclarations: false,
160
  
161
  // JSX configuration
162
  ecmaFeatures: {
163
    jsx: true
164
  },
165
  jsxPragma: "React",
166
  jsxFragmentName: "Fragment",
167
  
168
  // Library targets
169
  lib: ["es2022", "dom", "dom.iterable"],
170
  
171
  // Debug and error handling
172
  debugLevel: ["typescript-eslint"],
173
  errorOnUnknownASTType: true,
174
  warnOnUnsupportedTypeScriptVersion: false,
175
  
176
  // Performance options
177
  cacheLifetime: {
178
    glob: 3600 // 1 hour
179
  }
180
};
181

182
// Project service configuration
183
const projectServiceConfig: ParserOptions = {
184
  projectService: {
185
    allowDefaultProject: ["*.js", "scripts/*.js"],
186
    defaultProject: "tsconfig.base.json",
187
    loadTypeScriptPlugins: true,
188
    maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 16
189
  },
190
  tsconfigRootDir: process.cwd()
191
};
192

193
// Multi-project monorepo configuration
194
const monorepoConfig: ParserOptions = {
195
  project: [
196
    "./packages/*/tsconfig.json",
197
    "./apps/*/tsconfig.json"
198
  ],
199
  projectFolderIgnoreList: [
200
    "**/node_modules/**",
201
    "**/dist/**",
202
    "**/build/**"
203
  ],
204
  tsconfigRootDir: __dirname
205
};
206
```
207

208
## Configuration Categories
209

210
### ECMAScript Configuration
211

212
Control which ECMAScript features are available:
213

214
- **ecmaVersion**: Target ECMAScript version (3, 5, 6-17, 2015-2026, 'latest')
215
- **sourceType**: Module system ('module', 'script', 'commonjs')
216
- **ecmaFeatures**: Additional language features (jsx, globalReturn)
217

218
### TypeScript Integration
219

220
Configure TypeScript-specific parsing behavior:
221

222
- **project**: TypeScript project configuration files
223
- **projectService**: Advanced project service options
224
- **tsconfigRootDir**: Root directory for tsconfig resolution
225
- **lib**: TypeScript library targets
226
- **experimentalDecorators**: Enable experimental decorator support
227
- **emitDecoratorMetadata**: Include decorator metadata
228
- **isolatedDeclarations**: Enable isolated declarations mode
229

230
### JSX and React Configuration
231

232
Settings for JSX parsing and React integration:
233

234
- **jsxPragma**: JSX factory function name (default: "React")
235
- **jsxFragmentName**: JSX fragment name (default: "Fragment")
236
- **ecmaFeatures.jsx**: Enable JSX parsing
237

238
### Debug and Error Handling
239

240
Control parser output and error behavior:
241

242
- **debugLevel**: Enable debug output for specific components
243
- **errorOnUnknownASTType**: Throw errors for unknown AST node types
244
- **errorOnTypeScriptSyntacticAndSemanticIssues**: Handle TypeScript errors
245
- **warnOnUnsupportedTypeScriptVersion**: Version compatibility warnings
246

247
### Performance and Caching
248

249
Options to optimize parser performance:
250

251
- **cacheLifetime**: Configure glob pattern caching
252
- **range**: Include source range information
253
- **tokens**: Include token information
254
- **programs**: Reuse existing TypeScript programs
255

256
**Common Configuration Patterns:**
257

258
```typescript
259
// Strict TypeScript project
260
const strictConfig: ParserOptions = {
261
  project: true, // Use nearest tsconfig.json
262
  errorOnTypeScriptSyntacticAndSemanticIssues: true,
263
  warnOnUnsupportedTypeScriptVersion: true
264
};
265

266
// Legacy JavaScript with some TypeScript features
267
const legacyConfig: ParserOptions = {
268
  ecmaVersion: 5,
269
  sourceType: "script",
270
  experimentalDecorators: true // Allow decorators in legacy code
271
};
272

273
// Modern full-stack application
274
const fullStackConfig: ParserOptions = {
275
  ecmaVersion: "latest",
276
  sourceType: "module",
277
  project: ["./src/tsconfig.json", "./server/tsconfig.json"],
278
  lib: ["es2023", "dom", "node"],
279
  ecmaFeatures: { jsx: true },
280
  jsxPragma: "React",
281
  extraFileExtensions: [".vue", ".svelte"]
282
};
283
```