0
# Oxlint
1

2
Oxlint is a high-performance JavaScript and TypeScript linter written in Rust, providing 50-100x faster linting than ESLint while maintaining compatibility with JavaScript and TypeScript standards. It features comprehensive rule coverage, zero-configuration setup for immediate use, and integrates seamlessly with development workflows.
3

4
## Package Information
5

6
- **Package Name**: oxlint
7
- **Package Type**: npm (binary distribution), cargo (Rust crate)
8
- **Language**: Rust with JavaScript/TypeScript bindings
9
- **Installation**:
10
  - npm: `npm install -D oxlint`
11
  - npx: `npx --yes oxlint@latest`
12
  - cargo: Available as part of oxc workspace
13
- **Requirements**: Node.js >=20.0.0 (for npm bindings)
14

15
## Core Usage
16

17
### Command Line Interface
18

19
```bash
20
# Basic usage
21
oxlint [OPTIONS] [PATH...]
22

23
# Quick start - lint current directory
24
npx oxlint@latest
25

26
# Lint specific files/directories
27
oxlint src/ test/
28
oxlint --config .oxlintrc.json src/
29

30
# Apply automatic fixes
31
oxlint --fix src/
32

33
# Custom output format
34
oxlint --format json src/
35
```
36

37
### Basic Configuration File
38

39
`.oxlintrc.json`:
40

41
```json
42
{
43
  "$schema": "./node_modules/oxlint/configuration_schema.json",
44
  "plugins": ["typescript", "react", "import"],
45
  "env": {
46
    "browser": true,
47
    "node": true
48
  },
49
  "rules": {
50
    "eqeqeq": "error",
51
    "no-debugger": "warn",
52
    "react/jsx-uses-vars": "error"
53
  }
54
}
55
```
56

57
### Node.js API Usage
58

59
```typescript
60
import { lint } from "oxlint";
61

62
// JavaScript plugin interface (experimental)
63
// Available on 64-bit little-endian platforms only
64
const success = await lint(
65
  (pluginPath) => loadPluginFromPath(pluginPath),
66
  (filePath, bufferId, buffer, ruleIds) => processLintResults(filePath, buffer, ruleIds)
67
);
68
```
69

70
## Architecture
71

72
Oxlint is built around several key components:
73

74
- **CLI Interface**: Command-line parser with extensive configuration options
75
- **Linting Engine**: High-performance Rust-based linting core from oxc_linter
76
- **Plugin System**: Modular plugins for different frameworks and rule sets
77
- **Configuration System**: ESLint-compatible configuration with JSON schema validation
78
- **Output Formatters**: Multiple output formats for different CI/CD and editor integrations
79
- **Fix Engine**: Safe automatic code fixing for compatible rules
80
- **NAPI Bindings**: JavaScript/TypeScript API through Node.js native bindings
81
- **Multi-platform**: Support for Windows, macOS, Linux on x64 and ARM64
82

83
## Capabilities
84

85
### Command Line Interface
86

87
Comprehensive CLI with support for file selection, rule configuration, plugin management, and output formatting. Includes advanced options for parallel processing and configuration debugging.
88

89
```bash { .api }
90
oxlint [OPTIONS] [PATH...]
91
```
92

93
[Command Line Interface](./cli.md)
94

95
### Configuration System
96

97
ESLint-compatible configuration system supporting rules, plugins, environments, and file-specific overrides. Uses JSON schema for validation and IDE integration.
98

99
```json { .api }
100
{
101
  "plugins": string[],
102
  "rules": Record<string, "off" | "warn" | "error" | [string, any]>,
103
  "env": Record<string, boolean>,
104
  "overrides": Array<ConfigOverride>
105
}
106
```
107

108
[Configuration](./configuration.md)
109

110
### Plugin System
111

112
Modular plugin architecture supporting built-in and external plugins for different frameworks, testing libraries, and coding standards.
113

114
```bash { .api }
115
# Enable/disable plugins
116
oxlint --react-plugin --import-plugin src/
117
oxlint --disable-typescript-plugin src/
118
```
119

120
[Plugins](./plugins.md)
121

122
### Output Formatting
123

124
Multiple output format options for integration with different tools, CI/CD systems, and development environments.
125

126
```bash { .api }
127
# Available formats
128
oxlint --format default|json|stylish|checkstyle|github|gitlab|junit|unix
129
```
130

131
[Output Formats](./output-formats.md)
132

133
### Rule Categories and Management
134

135
Hierarchical rule categorization system with fine-grained control over rule severity and scope.
136

137
```bash { .api }
138
# Rule management
139
oxlint -A all -D correctness -W suspicious
140
oxlint --allow no-debugger --deny pedantic
141
```
142

143
[Rule Management](./rules.md)
144

145
### Node.js/JavaScript API
146

147
Experimental JavaScript plugin interface for advanced integrations and custom linting workflows.
148

149
```typescript { .api }
150
// Main lint function for JavaScript plugins
151
function lint(
152
  loadPlugin: (path: string) => Promise<string>,
153
  lintFile: (filePath: string, bufferId: number, buffer: Uint8Array | null, ruleIds: number[]) => string
154
): Promise<boolean>;
155
```
156

157
[Node.js API](./nodejs-api.md)
158

159
### Environment Variables
160

161
Runtime configuration through environment variables.
162

163
```bash { .api }
164
# Control logging levels and targets
165
OXC_LOG=oxc_resolver oxlint --import-plugin src/
166

167
# Version override (build-time)
168
OXC_VERSION=custom-build oxlint --version
169
```
170

171
### Platform Support
172

173
Supported platforms for npm binary distribution:
174
- Windows: x64, ARM64
175
- macOS: x64 (Intel), ARM64 (Apple Silicon)
176
- Linux: x64 GNU/musl, ARM64 GNU/musl
177

178
### File Extensions
179

180
Supported file extensions for linting:
181
- JavaScript: `.js`, `.mjs`, `.cjs`, `.jsx`
182
- TypeScript: `.ts`, `.mts`, `.cts`, `.tsx`
183
- Vue: `.vue` (with vue plugin)
184
- Svelte: `.svelte` (basic support)
185
- Astro: `.astro` (basic support)
186

187
## Types
188

189
```typescript { .api }
190
// Main CLI result enumeration
191
enum CliRunResult {
192
  None,
193
  LintSucceeded,
194
  LintFoundErrors,
195
  LintMaxWarningsExceeded,
196
  LintNoWarningsAllowed,
197
  LintNoFilesFound,
198
  PrintConfigResult,
199
  ConfigFileInitSucceeded,
200
  ConfigFileInitFailed,
201
  InvalidOptionConfig,
202
  InvalidOptionTsConfig,
203
  InvalidOptionSeverityWithoutFilter,
204
  InvalidOptionSeverityWithoutPluginName,
205
  InvalidOptionSeverityWithoutRuleName,
206
  TsGoLintError
207
}
208

209
// Output format options
210
enum OutputFormat {
211
  Default,
212
  Json,
213
  Github,
214
  Gitlab,
215
  Unix,
216
  Checkstyle,
217
  Stylish,
218
  JUnit
219
}
220

221
// Rule severity levels
222
enum AllowWarnDeny {
223
  Allow,
224
  Warn,
225
  Deny
226
}
227

228
// Node.js plugin interface types
229
type LoadPluginCallback = (path: string) => Promise<string>;
230
type LintFileCallback = (
231
  filePath: string,
232
  bufferId: number,
233
  buffer: Uint8Array | null,
234
  ruleIds: number[]
235
) => string;
236

237
// Platform architecture types
238
type SupportedPlatform =
239
  | "win32-x64" | "win32-arm64"
240
  | "linux-x64-gnu" | "linux-arm64-gnu"
241
  | "linux-x64-musl" | "linux-arm64-musl"
242
  | "darwin-x64" | "darwin-arm64";
243

244
// Exit codes mapping
245
interface ExitCodes {
246
  success: 0;
247
  failure: 1;
248
  // Maps to CliRunResult enum values
249
}
250
```