Skip to content

Commit 06bce5d

Browse files
CopilotBoshen
Copilot
and
Boshen
committed
Transform linter.md into comprehensive getting started guide with Next Steps section
Co-authored-by: Boshen <[email protected]>
1 parent e9e9d2a commit 06bce5d

File tree

1 file changed

+237
-56
lines changed

1 file changed

+237
-56
lines changed

‎src/docs/guide/usage/linter.md

Lines changed: 237 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,41 @@ badges:
66
alt: npm weekly downloads
77
---
88

9-
# Linter (oxlint)
9+
# Getting Started with Oxlint
1010

1111
<AppBadgeList />
1212

13-
Oxlint is designed to catch erroneous or useless code without requiring any configurations by default.
13+
Oxlint is an extremely fast JavaScript and TypeScript linter designed to catch erroneous or useless code without requiring any configurations by default. Get up and running in seconds!
14+
15+
## Quick Start
16+
17+
The fastest way to try Oxlint is to run it directly on your project:
18+
19+
::: code-group
20+
21+
```sh [npm]
22+
$ npx oxlint@latest
23+
```
24+
25+
```sh [pnpm]
26+
$ pnpm dlx oxlint@latest
27+
```
28+
29+
```sh [yarn]
30+
$ yarn dlx oxlint@latest
31+
```
32+
33+
```sh [bun]
34+
$ bunx oxlint@latest
35+
```
36+
37+
```sh [deno]
38+
$ deno run npm:oxlint@latest
39+
```
40+
41+
:::
42+
43+
That's it! Oxlint will automatically scan your JavaScript and TypeScript files and report any issues it finds.
1444

1545
:::info
1646
At this stage, Oxlint can be used to fully replace ESLint in small to medium projects.
@@ -19,28 +49,20 @@ For larger projects, our advice is to turn off ESLint rules via [eslint-plugin-o
1949
and run Oxlint before ESLint in your local or CI setup for a quicker feedback loop.
2050
:::
2151

22-
## Features
23-
24-
- 50 - 100 times faster than ESLint, and scales with the number of CPU cores ([benchmark](https://github.com/oxc-project/bench-javascript-linter)).
25-
- Over 520 rules with a growing list from `eslint`, `typescript`, `eslint-plugin-react`, `eslint-plugin-jest`, `eslint-plugin-unicorn`, `eslint-plugin-jsx-a11y` and [many more](https://github.com/oxc-project/oxc/issues/481).
26-
- Supports
27-
- [`.oxlintrc.json` configuration file](./linter/config).
28-
- [Nested configuration file](./linter/nested-config)
29-
- [Comment disabling](./linter/config.html#configuring-rules-via-inline-configuration-comments).
30-
- [Automatic Fixes](./linter/automatic-fixes)
52+
## Why Oxlint?
3153

32-
## Language Support
54+
- **⚡ Blazingly Fast**: 50-100 times faster than ESLint, scales with CPU cores ([benchmark](https://github.com/oxc-project/bench-javascript-linter))
55+
- **📦 Zero Configuration**: Works out of the box with sensible defaults
56+
- **🛠️ Rich Rule Set**: Over 520 rules from `eslint`, `typescript`, `eslint-plugin-react`, `eslint-plugin-jest`, `eslint-plugin-unicorn`, `eslint-plugin-jsx-a11y` and [many more](https://github.com/oxc-project/oxc/issues/481)
57+
- **🔧 Auto-fixing**: Automatically fix many issues with `--fix`
58+
- **⚙️ Configurable**: Support for [configuration files](./linter/config), [nested configs](./linter/nested-config), and [comment disabling](./linter/config.html#configuring-rules-via-inline-configuration-comments)
3359

34-
- Supports:
35-
- JavaScript and TypeScript by their extensions `js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts` and `tsx`.
36-
- `<script>` content of `.vue`, `.astro` and `.svelte` files.
37-
- No support for:
38-
- [type-aware rules](https://typescript-eslint.io/getting-started/typed-linting) defined by `typescript-eslint`.
39-
- [stylistic rules](https://eslint.style).
4060

4161
## Installation
4262

43-
Run `oxlint` directly at the root of your repository:
63+
### Try it now (Recommended)
64+
65+
Run `oxlint` directly at the root of your repository to try it without installing:
4466

4567
::: code-group
4668

@@ -66,6 +88,8 @@ $ deno run npm:oxlint@latest
6688

6789
:::
6890

91+
### Install to your project
92+
6993
Or save it to your package.json:
7094

7195
::: code-group
@@ -88,84 +112,241 @@ $ bun add -D oxlint
88112

89113
:::
90114

91-
`oxlint` does not require Node.js, the binaries can be downloaded from the [latest GitHub releases](https://github.com/oxc-project/oxc/releases/latest).
115+
Then run it via npm scripts:
92116

93-
## Command-line Interface
117+
```json [package.json]
118+
{
119+
"scripts": {
120+
"lint": "oxlint",
121+
"lint:fix": "oxlint --fix"
122+
}
123+
}
124+
```
94125

95-
See [Command-line Interface](./linter/cli)
126+
### Standalone Binary
96127

97-
## Configuration File
128+
`oxlint` does not require Node.js. The binaries can be downloaded from the [latest GitHub releases](https://github.com/oxc-project/oxc/releases/latest) as a standalone binary, perfect for CI environments without Node.js.
98129

99-
See [Configuration File](./linter/config)
130+
## Basic Usage
100131

101-
## Migrate from eslint flat config
132+
### Lint your project
102133

103-
If you have an existing `eslint.config.*` file, you can convert it to an `.oxlintrc.json` config with [oxlint-migrate](https://github.com/oxc-project/oxlint-migrate).
134+
```sh
135+
$ oxlint
136+
```
104137

105-
## Integration
138+
Oxlint will automatically find and lint all JavaScript and TypeScript files in your project.
106139

107-
### ESLint
140+
### Fix issues automatically
108141

109-
If you are looking for a way to use oxlint in projects that still need ESLint, you can use [eslint-plugin-oxlint](https://github.com/oxc-project/eslint-plugin-oxlint) to turn off ESLint rules that are already supported by oxlint. So you can enjoy the speed of oxlint while still using ESLint.
142+
```sh
143+
$ oxlint --fix
144+
```
110145

111-
### lint-staged
146+
Many issues can be automatically fixed. This is safe and won't change your code's behavior.
112147

113-
```json [package.json]
114-
{
115-
"lint-staged": {
116-
"**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue,astro,svelte}": "oxlint"
117-
}
118-
}
148+
### Check specific files or directories
149+
150+
```sh
151+
$ oxlint src/
152+
$ oxlint src/components/*.tsx
153+
$ oxlint --include "**/*.js" --include "**/*.ts"
119154
```
120155

121-
### VSCode Extension
156+
## Next Steps
157+
158+
Now that you have Oxlint running, here's how to get the most out of it:
122159

123-
Download the official VSCode extension from the
160+
### 🔧 Customize Rules and Configuration
124161

125-
- [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode)
126-
- [Open VSX Registry](https://open-vsx.org/extension/oxc/oxc-vscode)
162+
Create an `.oxlintrc.json` file in your project root to customize which rules are enabled:
127163

128-
### Zed Extension
164+
```json [.oxlintrc.json]
165+
{
166+
"rules": {
167+
"no-console": "warn",
168+
"no-debugger": "error",
169+
"prefer-const": "error"
170+
},
171+
"plugins": ["react", "jsx-a11y"],
172+
"env": {
173+
"browser": true,
174+
"node": true
175+
}
176+
}
177+
```
129178

130-
https://zed.dev/extensions?query=oxc
179+
📚 **Learn more**: [Configuration Guide](./linter/config) | [Available Rules](./linter/rules) | [Plugins](./linter/plugins)
131180

132-
### Continuous Integration
181+
### 🚀 Set Up CI/CD Integration
133182

134-
Since `oxlint` only takes a few seconds to run, we recommend running `oxlint` before ESLint for faster feedback loops.
183+
Add Oxlint to your continuous integration for consistent code quality:
135184

136185
#### GitHub Actions
137186

138-
```yaml
187+
```yaml [.github/workflows/lint.yml]
139188
jobs:
140-
oxlint:
141-
name: Lint JS
189+
lint:
142190
runs-on: ubuntu-latest
143191
steps:
144192
- uses: actions/checkout@v4
145-
- run: npx --yes oxlint@0.0.0 --deny-warnings # change to the latest release
193+
- run: npx --yes oxlint@latest --deny-warnings
146194
```
147195
148-
It is advised to pin the version, otherwise CI may fail after a new release.
196+
#### Other CI Systems
149197
150-
### pre-commit
198+
- **GitLab CI**: `npx oxlint@latest --deny-warnings`
199+
- **Bitbucket Pipelines**: `npx oxlint@latest --deny-warnings`
200+
- **Jenkins**: `npx oxlint@latest --deny-warnings`
151201

202+
💡 **Tip**: Pin the version in CI to avoid surprises: `npx --yes [email protected]`
203+
204+
📚 **Learn more**: [CI Integration Examples](./linter/config#continuous-integration)
205+
206+
### 🔄 Migrate from ESLint
207+
208+
Already using ESLint? Here's how to transition smoothly:
209+
210+
1. **Run both side-by-side** initially:
211+
```json [package.json]
212+
{
213+
"scripts": {
214+
"lint": "oxlint && eslint .",
215+
"lint:fix": "oxlint --fix && eslint . --fix"
216+
}
217+
}
218+
```
219+
220+
2. **Use eslint-plugin-oxlint** to disable overlapping rules:
221+
```sh
222+
npm install -D eslint-plugin-oxlint
223+
```
224+
225+
3. **Convert your ESLint config** with [oxlint-migrate](https://github.com/oxc-project/oxlint-migrate):
226+
```sh
227+
npx oxlint-migrate
228+
```
229+
230+
📚 **Learn more**: [Migration Guide](./linter/config#migrate-from-eslint-flat-config)
231+
232+
### ⚡ Unlock Advanced Features
233+
234+
#### Automatic Fixes
235+
Fix issues automatically while preserving your code's behavior:
236+
```sh
237+
oxlint --fix
238+
```
239+
240+
#### Framework-Specific Linting
241+
Enable rules for your framework:
242+
```json [.oxlintrc.json]
243+
{
244+
"plugins": ["react", "vue", "jsx-a11y"],
245+
"settings": {
246+
"react": {
247+
"version": "detect"
248+
}
249+
}
250+
}
251+
```
252+
253+
#### Nested Configuration
254+
Use different rules for different parts of your project:
255+
```json [src/tests/.oxlintrc.json]
256+
{
257+
"extends": ["../../../.oxlintrc.json"],
258+
"plugins": ["jest"],
259+
"env": {
260+
"jest": true
261+
}
262+
}
263+
```
264+
265+
📚 **Learn more**: [Automatic Fixes](./linter/automatic-fixes) | [Nested Config](./linter/nested-config)
266+
267+
### 🏗️ IDE and Editor Integration
268+
269+
Get real-time linting in your editor:
270+
271+
- **VS Code**: Install the [Oxc VS Code Extension](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode)
272+
- **Zed**: Search for "oxc" in [Zed Extensions](https://zed.dev/extensions?query=oxc)
273+
- **Other Editors**: Use the [Language Server Protocol](./linter/config#language-server-protocol)
274+
275+
### 🛠️ Development Workflow Integration
276+
277+
#### Pre-commit Hooks with lint-staged
278+
```json [package.json]
279+
{
280+
"lint-staged": {
281+
"**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue,astro,svelte}": "oxlint"
282+
}
283+
}
284+
```
285+
286+
#### pre-commit Framework
152287
```yaml [.pre-commit-hooks.yaml]
153288
repos:
154289
- repo: https://github.com/oxc-project/mirrors-oxlint
155-
rev: v0.0.0 # change to the latest version
290+
rev: v0.x.x # Use the latest version
156291
hooks:
157292
- id: oxlint
158293
verbose: true
159294
```
160295

161-
### Unplugin
296+
#### Build Tool Integration
297+
- **Vite**: [vite-plugin-oxlint](https://www.npmjs.com/package/vite-plugin-oxlint)
298+
- **Universal**: [unplugin-oxlint](https://www.npmjs.com/package/unplugin-oxlint)
299+
300+
### 📊 Performance Optimization
301+
302+
For large codebases:
303+
304+
1. **Use ignore patterns** to skip unnecessary files:
305+
```json [.oxlintrc.json]
306+
{
307+
"ignorePatterns": ["dist/", "build/", "node_modules/"]
308+
}
309+
```
310+
311+
2. **Leverage parallel processing**: Oxlint automatically uses all CPU cores
312+
313+
3. **Run incrementally**: Only lint changed files in CI:
314+
```sh
315+
git diff --name-only --cached | grep -E '\.(js|ts|jsx|tsx)$' | xargs oxlint
316+
```
162317

163-
https://www.npmjs.com/package/unplugin-oxlint
318+
### 🤝 Get Help and Stay Updated
319+
320+
- **📖 Documentation**: [oxc.rs](https://oxc.rs)
321+
- **💬 Community**: [Discord Server](https://discord.gg/9uXCAwqQZW)
322+
- **🐛 Issues**: [GitHub Issues](https://github.com/oxc-project/oxc/issues)
323+
- **🌟 Stay Updated**: [Follow @boshen_c](https://twitter.com/boshen_c) on Twitter
324+
325+
---
326+
327+
## Technical Details
328+
329+
### Command-line Interface
330+
331+
See [Command-line Interface](./linter/cli)
332+
333+
### Configuration File
334+
335+
See [Configuration File](./linter/config)
336+
337+
### Migrate from eslint flat config
338+
339+
If you have an existing `eslint.config.*` file, you can convert it to an `.oxlintrc.json` config with [oxlint-migrate](https://github.com/oxc-project/oxlint-migrate).
164340

165-
### Vite plugin
341+
### Language Support
166342

167-
https://www.npmjs.com/package/vite-plugin-oxlint
343+
- **Supported**:
344+
- JavaScript and TypeScript by their extensions `js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts` and `tsx`
345+
- `<script>` content of `.vue`, `.astro` and `.svelte` files
346+
- **Not supported**:
347+
- [Type-aware rules](https://typescript-eslint.io/getting-started/typed-linting) defined by `typescript-eslint`
348+
- [Stylistic rules](https://eslint.style)
168349

169-
## System Requirements
350+
### System Requirements
170351

171352
`oxlint` is built for darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64 and win32-x64.

0 commit comments

Comments
 (0)