0
# Configuration
1

2
Oxlint uses ESLint-compatible JSON configuration files with additional oxlint-specific features. Configuration files support comments and provide JSON schema validation for IDE integration.
3

4
## Configuration File Format
5

6
### Default Configuration File
7

8
Oxlint automatically looks for `.oxlintrc.json` in the current working directory. You can specify a custom configuration file using the `--config` option.
9

10
```json { .api }
11
{
12
  "$schema": "./node_modules/oxlint/configuration_schema.json",
13
  "categories": {
14
    "correctness": "warn",
15
    "suspicious": "warn",
16
    "pedantic": "off"
17
  },
18
  "env": {
19
    "browser": true,
20
    "node": true,
21
    "es6": true
22
  },
23
  "extends": ["./base-config.json"],
24
  "globals": {
25
    "myGlobal": "readonly",
26
    "myWritableGlobal": "writable"
27
  },
28
  "ignorePatterns": ["dist/**", "**/*.d.ts"],
29
  "overrides": [
30
    {
31
      "files": ["*.test.js", "*.spec.js"],
32
      "rules": {
33
        "no-unused-vars": "off"
34
      }
35
    }
36
  ],
37
  "plugins": ["typescript", "react", "import"],
38
  "rules": {
39
    "eqeqeq": "error",
40
    "no-debugger": "warn",
41
    "prefer-const": ["error", { "destructuring": "all" }]
42
  },
43
  "settings": {
44
    "react": {
45
      "version": "detect"
46
    },
47
    "import/resolver": {
48
      "typescript": true
49
    }
50
  }
51
}
52
```
53

54
## Configuration Properties
55

56
### Categories
57

58
Control entire rule categories with a single setting.
59

60
```json { .api }
61
{
62
  "categories": {
63
    "correctness": "error" | "warn" | "off",
64
    "suspicious": "error" | "warn" | "off",
65
    "pedantic": "error" | "warn" | "off",
66
    "perf": "error" | "warn" | "off",
67
    "style": "error" | "warn" | "off",
68
    "nursery": "error" | "warn" | "off",
69
    "restriction": "error" | "warn" | "off"
70
  }
71
}
72
```
73

74
### Environment Configuration
75

76
Enable predefined global variables for different environments.
77

78
```json { .api }
79
{
80
  "env": {
81
    "browser": boolean,
82
    "node": boolean,
83
    "es6": boolean,
84
    "es2017": boolean,
85
    "es2020": boolean,
86
    "es2021": boolean,
87
    "es2022": boolean,
88
    "worker": boolean,
89
    "amd": boolean,
90
    "mocha": boolean,
91
    "jasmine": boolean,
92
    "jest": boolean,
93
    "phantomjs": boolean,
94
    "jquery": boolean,
95
    "qunit": boolean,
96
    "prototypejs": boolean,
97
    "shelljs": boolean,
98
    "meteor": boolean,
99
    "mongo": boolean,
100
    "applescript": boolean,
101
    "nashorn": boolean,
102
    "serviceworker": boolean,
103
    "atomtest": boolean,
104
    "embertest": boolean,
105
    "webextensions": boolean,
106
    "greasemonkey": boolean,
107
    "builtin": boolean
108
  }
109
}
110
```
111

112
### Configuration Inheritance
113

114
Extend from other configuration files with relative path resolution.
115

116
```json { .api }
117
{
118
  "extends": string[]
119
}
120
```
121

122
### Global Variables
123

124
Define additional global variables and their mutability.
125

126
```json { .api }
127
{
128
  "globals": {
129
    [key: string]: "readonly" | "writable" | "off"
130
  }
131
}
132
```
133

134
### Ignore Patterns
135

136
Specify glob patterns for files and directories to exclude from linting.
137

138
```json { .api }
139
{
140
  "ignorePatterns": string[]
141
}
142
```
143

144
### File-Specific Overrides
145

146
Apply different rules to specific files or patterns.
147

148
```json { .api }
149
{
150
  "overrides": [
151
    {
152
      "files": string[],
153
      "excludedFiles": string[],
154
      "env": EnvironmentConfig,
155
      "globals": GlobalsConfig,
156
      "rules": RulesConfig,
157
      "settings": SettingsConfig
158
    }
159
  ]
160
}
161
```
162

163
### Plugin Configuration
164

165
Enable or configure specific linting plugins.
166

167
```json { .api }
168
{
169
  "plugins": [
170
    "eslint",               // Core ESLint rules (default)
171
    "typescript",           // @typescript-eslint rules (default)
172
    "@typescript-eslint",   // Alternative name for typescript
173
    "react",                // React-specific rules
174
    "react-hooks",          // React Hooks rules
175
    "import",               // ES6 import/export rules
176
    "import-x",             // Alternative name for import
177
    "unicorn",              // Unicorn rules (enabled by default)
178
    "oxc",                  // OXC-specific rules (enabled by default)
179
    "deepscan",             // Alternative name for oxc
180
    "jsdoc",                // JSDoc comment rules
181
    "jest",                 // Jest testing rules
182
    "vitest",               // Vitest testing rules
183
    "jsx-a11y",             // JSX accessibility rules
184
    "nextjs",               // Next.js rules
185
    "react-perf",           // React performance rules
186
    "promise",              // Promise usage rules
187
    "node",                 // Node.js rules
188
    "regex",                // Regex rules
189
    "vue"                   // Vue.js rules
190
  ]
191
}
192
```
193

194
### Rule Configuration
195

196
Configure individual linting rules with severity levels and options.
197

198
```json { .api }
199
{
200
  "rules": {
201
    [ruleName: string]:
202
      | "off" | "warn" | "error"
203
      | [("off" | "warn" | "error"), ...any[]]
204
  }
205
}
206
```
207

208
**Rule Severity Levels:**
209
- `"off"` or `0` - Disable the rule
210
- `"warn"` or `1` - Rule violations produce warnings (exit code 0 unless --deny-warnings)
211
- `"error"` or `2` - Rule violations produce errors (exit code 1)
212

213
**Rule Configuration with Options:**
214
Many rules accept additional configuration options:
215
```json
216
{
217
  "rules": {
218
    "prefer-const": ["error", { "destructuring": "all" }],
219
    "no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }]
220
  }
221
}
222
```
223

224
### Plugin Settings
225

226
Configure plugin-specific settings that affect rule behavior.
227

228
```json { .api }
229
{
230
  "settings": {
231
    "react": {
232
      "createClass": string,
233
      "pragma": string,
234
      "fragment": string,
235
      "version": string | "detect",
236
      "flowVersion": string
237
    },
238
    "import/resolver": {
239
      "node": {
240
        "extensions": string[]
241
      },
242
      "typescript": boolean | {
243
        "alwaysTryTypes": boolean,
244
        "project": string | string[]
245
      }
246
    },
247
    "import/ignore": string[],
248
    "import/extensions": string[],
249
    "import/core-modules": string[],
250
    "import/external-module-folders": string[]
251
  }
252
}
253
```
254

255
## Configuration Discovery
256

257
Oxlint discovers configuration files using the following priority order:
258

259
1. Command-line specified config (`--config path/to/config.json`)
260
2. `.oxlintrc.json` in current directory
261
3. `.oxlintrc.json` in parent directories (unless `--disable-nested-config`)
262
4. Built-in default configuration
263

264
## Schema Validation
265

266
Oxlint provides JSON Schema validation for configuration files:
267

268
```json
269
{
270
  "$schema": "./node_modules/oxlint/configuration_schema.json"
271
}
272
```
273

274
This enables IDE features like autocompletion, validation, and documentation tooltips.
275

276
## Configuration Debugging
277

278
### Print Resolved Configuration
279

280
```bash
281
oxlint --print-config
282
```
283

284
Outputs the final resolved configuration without performing linting.
285

286
### Disable Nested Configuration
287

288
```bash
289
oxlint --disable-nested-config
290
```
291

292
Prevents automatic discovery of configuration files in parent directories.
293

294
## Common Configuration Patterns
295

296
### TypeScript Project
297

298
```json
299
{
300
  "$schema": "./node_modules/oxlint/configuration_schema.json",
301
  "plugins": ["typescript"],
302
  "env": {
303
    "browser": true,
304
    "es6": true
305
  },
306
  "rules": {
307
    "@typescript-eslint/no-unused-vars": "error",
308
    "@typescript-eslint/explicit-function-return-type": "warn"
309
  }
310
}
311
```
312

313
### React Project
314

315
```json
316
{
317
  "$schema": "./node_modules/oxlint/configuration_schema.json",
318
  "plugins": ["react", "jsx-a11y"],
319
  "env": {
320
    "browser": true,
321
    "es6": true
322
  },
323
  "settings": {
324
    "react": {
325
      "version": "detect"
326
    }
327
  },
328
  "rules": {
329
    "react/jsx-uses-react": "error",
330
    "react/jsx-uses-vars": "error",
331
    "jsx-a11y/alt-text": "warn"
332
  }
333
}
334
```
335

336
### Node.js Project
337

338
```json
339
{
340
  "$schema": "./node_modules/oxlint/configuration_schema.json",
341
  "plugins": ["node"],
342
  "env": {
343
    "node": true,
344
    "es6": true
345
  },
346
  "rules": {
347
    "node/no-missing-import": "error",
348
    "node/no-unpublished-require": "warn"
349
  }
350
}
351
```
352

353
### Testing Configuration
354

355
```json
356
{
357
  "$schema": "./node_modules/oxlint/configuration_schema.json",
358
  "plugins": ["jest"],
359
  "overrides": [
360
    {
361
      "files": ["**/*.test.js", "**/*.spec.js"],
362
      "env": {
363
        "jest": true
364
      },
365
      "rules": {
366
        "jest/expect-expect": "error",
367
        "jest/no-disabled-tests": "warn"
368
      }
369
    }
370
  ]
371
}
372
```