diff --git a/src/docs/guide/usage/linter/ci.md b/src/docs/guide/usage/linter/ci.md index 284bfc0b9d0..f74f4a781bf 100644 --- a/src/docs/guide/usage/linter/ci.md +++ b/src/docs/guide/usage/linter/ci.md @@ -1,11 +1,17 @@ --- -title: Setup CI -description: Run Oxlint in CI. +title: Setup CI and other integrations +description: Run Oxlint in CI or as a git hook. --- -# Setup CI +# Setup CI and other integrations -## GitHub Actions +You can - and should - setup your CI pipeline to run Oxlint and fail the build on lint errors. + +This page also covers other integrations you may want to include, like git pre-commit hooks. + +## CI + +### GitHub Actions Create `.github/workflows/oxlint.yml`: @@ -34,8 +40,24 @@ jobs: - run: pnpm run lint --deny-warnings # given package.json scripts "lint": "oxlint" ``` +## Git hooks + +### lint-staged + +For JS/TS projects using [lint-staged](https://github.com/lint-staged/lint-staged), you can set up oxlint to run pre-commit as follows: + +```json +{ + "lint-staged": { + "*.{js,jsx,ts,tsx,mjs,cjs}": "pnpm run lint" + } +} +``` + ### pre-commit +If you use [pre-commit](https://pre-commit.com/) to manage git hooks, you can set up Oxlint as follows: + ```yaml [.pre-commit-hooks.yaml] repos: - repo: https://github.com/oxc-project/mirrors-oxlint @@ -45,10 +67,12 @@ repos: verbose: true ``` +## Other integrations + ### Unplugin -https://www.npmjs.com/package/unplugin-oxlint +Unplugin is supported via a [third-party package](https://www.npmjs.com/package/unplugin-oxlint) ### Vite plugin -https://www.npmjs.com/package/vite-plugin-oxlint +A Vite plugin is supported via a [third-party package](https://www.npmjs.com/package/vite-plugin-oxlint) diff --git a/src/docs/guide/usage/linter/config.md b/src/docs/guide/usage/linter/config.md index df621dad28d..ad90de2817f 100644 --- a/src/docs/guide/usage/linter/config.md +++ b/src/docs/guide/usage/linter/config.md @@ -17,7 +17,7 @@ To generate a starter config in the current directory: oxlint --init ``` -Oxlint automatically looks for a `.oxlintrc.json` in the current working directory. You can also pass a config explicitly: +Oxlint automatically looks for a `.oxlintrc.json` in the current working directory. You can also pass a config explicitly (note that this will disable nested config lookup): ```sh oxlint -c ./oxlintrc.json @@ -27,8 +27,8 @@ oxlint --config ./oxlintrc.json Notes: -- Only `.json` config files are supported, and configuration files support comments (JSONC). -- The configuration format aims to be compatible with ESLint v8 (`eslintrc.json`). +- Only `.json` config files are supported, but oxlint configuration files support comments (like jsonc). +- The configuration format aims to be compatible with ESLint v8's format (`eslintrc.json`). A minimal configuration looks like this: @@ -102,7 +102,7 @@ To configure rule options, use an array: } ``` -All available rules are listed in the [Rules reference](/docs/guide/usage/linter/rules). +All available rules, and their configuration options, are listed in the [Rules reference](/docs/guide/usage/linter/rules). ### Override severity from the CLI @@ -176,18 +176,21 @@ For plugin details and CLI flags such as `--import-plugin`, see [Native Plugins] ## Configure JS plugins (experimental) -Oxlint also supports JavaScript plugins via `jsPlugins`. This is intended for compatibility and advanced integrations. +Oxlint also supports JavaScript plugins via `jsPlugins`. This is intended for compatibility with existing ESLint plugins and advanced integrations. Notes: - JS plugins are experimental and not subject to semver. - JS plugins are not supported in the language server at present. -JS plugins can be declared as strings or as objects with an alias: +JS plugins can be declared as strings, or as objects with an alias: ```jsonc { - "jsPlugins": [{ "name": "my-eslint-react", "specifier": "eslint-plugin-react" }], + "jsPlugins": [ + "eslint-plugin-playwright", + { "name": "my-eslint-react", "specifier": "eslint-plugin-react" }, + ], } ``` @@ -212,6 +215,7 @@ Example: ```jsonc { + "$schema": "./node_modules/oxlint/configuration_schema.json", "rules": { "no-console": "error", }, diff --git a/src/docs/guide/usage/linter/editors.md b/src/docs/guide/usage/linter/editors.md index 0d919b6b37a..248f5dfe47b 100644 --- a/src/docs/guide/usage/linter/editors.md +++ b/src/docs/guide/usage/linter/editors.md @@ -39,7 +39,7 @@ Create `.vscode/extensions.json`: } ``` -2. Enable fix on save (optional). +2. Enable fix-on-save (optional). Add to `.vscode/settings.json`: @@ -51,6 +51,18 @@ Add to `.vscode/settings.json`: } ``` +3. Enable type-aware linting (optional). + +If you'd like to use type-aware rules and show type-related lint violations, ensure that `typeAware` is set to `true` in your VS Code settings (`.vscode/settings.json`): + +```jsonc +{ + "oxc.typeAware": true, +} +``` + +You also need to ensure `oxlint-tsgolint` is installed in your project. See [the type-aware linting docs](/docs/guide/usage/linter/type-aware) for more details. + ### Usage and configuration reference - [https://github.com/oxc-project/oxc/tree/main/editors/vscode](https://github.com/oxc-project/oxc/tree/main/editors/vscode) diff --git a/src/docs/guide/usage/linter/ignore-comments.md b/src/docs/guide/usage/linter/ignore-comments.md index 7aa34c0b457..6b9125f08eb 100644 --- a/src/docs/guide/usage/linter/ignore-comments.md +++ b/src/docs/guide/usage/linter/ignore-comments.md @@ -11,17 +11,17 @@ Oxlint supports line comments (`//`) and block comments (`/* */`). Comments must ## oxlint-disable -Disable one or more rules until the end of the file, or until they are re enabled. +Disable one or more rules until the end of the file, or until they are re-enabled. ```js -// Disable Oxlint for the rest of the file +// Disable all Oxlint rules for the rest of the file /* oxlint-disable */ // Disable a single rule in this file /* oxlint-disable no-console */ // Disable multiple rules in this file -/* oxlint-disable no-console, no-alert */ +/* oxlint-disable no-console, typescript/no-floating-promises */ ``` ## oxlint-enable @@ -44,17 +44,9 @@ console.log("Hello, world!"); // oxlint-disable-line no-console console.log(x++); // oxlint-disable-line no-console, no-plusplus ``` -## oxlint-enable-line - -Enable one or more rules on the current line. - -```js -// oxlint-enable-line no-console -``` - ## oxlint-disable-next-line -Disable one or more rules on the line following the comment, then re enable them automatically. +Disable one or more rules on the line following the comment, then re-enables them for subsequent lines. ```js // oxlint-disable-next-line no-console @@ -65,14 +57,6 @@ console.log(x++); // not allowed because the previous comment only applied to th console.log("Hello, world!"); // allowed ``` -## oxlint-enable-next-line - -Enable one or more rules on the line following the comment, then re enable automatically. - -```js -// oxlint-enable-next-line no-console -``` - ## ESLint compatibility For compatibility with existing ESLint codebases, the same keywords are supported with `oxlint` replaced by `eslint`, such as `/* eslint-disable */` and `// eslint-disable-next-line`. diff --git a/src/docs/guide/usage/linter/nested-config.md b/src/docs/guide/usage/linter/nested-config.md index fb3cd8564de..eef59ffb23a 100644 --- a/src/docs/guide/usage/linter/nested-config.md +++ b/src/docs/guide/usage/linter/nested-config.md @@ -42,7 +42,9 @@ Configuration files are not automatically merged. A config in a child directory Command line options override configuration files, regardless of whether they come from a parent or child directory. -Passing `--config` disables nested config lookup and applies a single configuration file. +Passing an explicit config file location using `-c` or `--config` disables nested config lookup, and Oxlint will only use that single configuration file. + +You can also disable nested configs with the `--disable-nested-configs` flag. ## Monorepo pattern: share a base config with extends diff --git a/src/docs/guide/usage/linter/plugins.md b/src/docs/guide/usage/linter/plugins.md index 70fa8fb842b..65decc2cfc6 100644 --- a/src/docs/guide/usage/linter/plugins.md +++ b/src/docs/guide/usage/linter/plugins.md @@ -5,21 +5,35 @@ description: Enable built in plugin rule sets and extend Oxlint with ESLint comp # Built-in Plugins -Oxlint includes built in implementations of many popular ESLint plugin rule sets. Most rules in the `recommended` configs are already implemented, so you can get useful results without extra setup. +Oxlint includes built-in implementations of many popular ESLint plugin rule sets. Most rules in the `recommended` configs are already implemented, so you can get useful results without extra setup. -Oxlint also supports plugins written in JavaScript with an ESLint compatible API. See [JS Plugins](./js-plugins.md). +Oxlint also supports plugins written in JavaScript with an ESLint-compatible API. See [JS Plugins](./js-plugins.md). ## What a plugin means in Oxlint A plugin is a named group of rules. Enabling a plugin makes its rules available, and category flags control which rules are enabled and at what severity. -If you are migrating from ESLint, plugins map to the ecosystems you already know, such as import, react, jsx a11y, jest, unicorn, and more. +If you are migrating from ESLint, plugins map to the ecosystems you already know, such as import, react, jsx-a11y, jest, unicorn, and more. ## Enable a plugin +It is **strongly recommended** to use a config file to enable plugins, as it makes it considerably easier to manage and share with other developers on a project. + +### Enable in a config file + +You can also enable plugins in `.oxlintrc.json` using the `plugins` field: + +```json +{ + "plugins": ["import"] +} +``` + +Setting `plugins` **overwrites the default plugin set**. The list should include every plugin you want enabled. + ### Enable with the CLI -Enable a plugin using a `---plugin` flag. +You can also enable a plugin using a `---plugin` CLI flag. Example, enable the import plugin: @@ -39,19 +53,21 @@ Correctness rules are enabled by default. Tip: run `oxlint --help` to see the full list of plugin flags. -### Enable in a config file +## Disable default plugins -You can also enable plugins in `.oxlintrc.json` using the `plugins` field: +### Disable default plugins in a config file + +To disable all default plugins in a config file, set `plugins` to an empty array: ```json { - "plugins": ["import"] + "plugins": [] } ``` -Setting `plugins` overwrites the default plugin set. The list should include every plugin you want enabled. +This disables all default plugins and uses only the base rule set. -## Disable default plugins +### Disable default plugins with the CLI Several plugins are enabled by default. You can disable a default plugin with `--disable--plugin`. @@ -61,46 +77,34 @@ Example, disable unicorn: oxlint --disable-unicorn-plugin ``` -Only default plugins support being disabled. Non default plugins can simply be omitted. - -### Disable default plugins in a config file - -To disable all default plugins in a config file, set `plugins` to an empty array: - -```json -{ - "plugins": [] -} -``` - -This disables all default plugins and uses only the base rule set. +Only default plugins support being disabled. Non-default plugins can simply be omitted. ## Supported plugins -This table lists the built in plugins and where they come from. - -| Plugin name | Default | Source | -| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ | -| `eslint` | Yes | ESLint core rules | -| `typescript` | Yes | TypeScript rules from the typescript eslint ecosystem. Type aware rules are available in alpha using the type aware mode | -| `unicorn` | Yes | eslint plugin unicorn | -| `react` | No | eslint plugin react and eslint plugin react hooks | -| `react-perf` | No | eslint plugin react perf | -| `nextjs` | No | eslint plugin next | -| `oxc` | Yes | Oxc specific rules and selected rules ported from deepscan | -| `import` | No | eslint plugin import | -| `jsdoc` | No | eslint plugin jsdoc | -| `jsx-a11y` | No | eslint plugin jsx a11y | -| `node` | No | eslint plugin n | -| `promise` | No | eslint plugin promise | -| `jest` | No | eslint plugin jest | -| `vitest` | No | eslint plugin vitest | -| `vue` | No | eslint plugin vue rules that work with script tags | +This table lists the built-in plugins and where they come from. + +| Plugin name | Default | Source | +| ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `eslint` | Yes | ESLint core rules | +| `typescript` | Yes | TypeScript rules from typescript-eslint (aka `@typescript-eslint/plugin`). Type-aware rules are available in alpha using [the type-aware mode](./type-aware.md). | +| `unicorn` | Yes | eslint-plugin-unicorn | +| `react` | No | eslint-plugin-react and eslint-plugin-react-hooks | +| `react-perf` | No | eslint-plugin-react-perf | +| `nextjs` | No | @next/eslint-plugin-next | +| `oxc` | Yes | Oxc-specific rules and selected rules ported from deepscan | +| `import` | No | eslint-plugin-import (also equivalent to eslint-plugin-import-x) | +| `jsdoc` | No | eslint-plugin-jsdoc | +| `jsx-a11y` | No | eslint-plugin-jsx-a11y | +| `node` | No | eslint-plugin-n | +| `promise` | No | eslint-plugin-promise | +| `jest` | No | eslint-plugin-jest | +| `vitest` | No | @vitest/eslint-plugin aka eslint-plugin-vitest | +| `vue` | No | eslint-plugin-vue rules that work with script tags | For the current status of rule coverage, see the linter [product plan issue](https://github.com/oxc-project/oxc/issues/481). ## Adding new plugins -Oxlint focuses on supporting the ecosystem through built in plugins and ESLint compatible JavaScript plugins. Contributions that add rules to existing built in plugins are encouraged. +Oxlint focuses on supporting the ecosystem through built-in plugins and ESLint-compatible JavaScript plugins. [Contributions that add rules](/docs/contribute/linter/adding-rules) to existing built-in plugins are encouraged. -If you think a rule set should be implemented as a built in plugin, open a discussion first. +If you think a rule set should be implemented as a built-in plugin, please [open a GitHub discussion](https://github.com/oxc-project/oxc/discussions/new?category=feature-request) first. diff --git a/src/docs/guide/usage/linter/quickstart.md b/src/docs/guide/usage/linter/quickstart.md index cfdbfbd5263..448b03ac9f9 100644 --- a/src/docs/guide/usage/linter/quickstart.md +++ b/src/docs/guide/usage/linter/quickstart.md @@ -68,14 +68,18 @@ Initialize the `.oxlintrc.json` config with default values: oxlint --init ``` -Use a config file explicitly: +Then run Oxlint: ```sh -oxlint -c ./oxlintrc.json -# or -oxlint --config ./oxlintrc.json +oxlint ``` +::: tip +If you are migrating from ESLint, use [`@oxlint/migrate`](https://github.com/oxc-project/oxlint-migrate) to generate an Oxlint config from your existing ESLint flat file config. +::: + + + ### Fix problems Apply safe fixes: @@ -118,12 +122,6 @@ Disable ignore handling: oxlint --no-ignore ``` -Follow symlinks (Oxlint ignores symlinks by default): - -```sh -oxlint --symlinks -``` - See [Ignore files](/docs/guide/usage/linter/ignore-files). ### Fail CI reliably @@ -156,7 +154,7 @@ Select an output format: oxlint -f json ``` -Available formats include: `default`, `json`, `unix`, `checkstyle`, `github`, `stylish`. +Available formats include: `default`, `json`, `unix`, `checkstyle`, `github`, `gitlab`, `junit`, `stylish`. ### Inspect the effective configuration @@ -168,7 +166,7 @@ oxlint --print-config path/to/file.ts ### List available rules -List registered rules: +List registered rules, including those enabled by your current oxlint config: ```sh oxlint --rules diff --git a/src/docs/guide/usage/linter/type-aware.md b/src/docs/guide/usage/linter/type-aware.md index abba342bf7d..7706b154f4b 100644 --- a/src/docs/guide/usage/linter/type-aware.md +++ b/src/docs/guide/usage/linter/type-aware.md @@ -45,7 +45,7 @@ bun add -D oxlint-tsgolint@latest ## Running type-aware linting -Enable type-aware linting with the `--type-aware` flag: +To run Oxlint with type-aware linting, you must pass the `--type-aware` flag: ```bash oxlint --type-aware @@ -55,6 +55,8 @@ When enabled, Oxlint runs standard rules and type-aware rules in the `typescript Type-aware linting is opt-in and does not run unless the flag is provided. +In editor and LSP-based integrations like VS Code, type-aware linting can be enabled by setting the `typeAware` option to `true`, see the [Editors](./editors) page for more information. + ### Monorepos and build outputs Type-aware linting requires resolved type information. @@ -134,9 +136,12 @@ oxlint --type-aware --report-unused-disable-directives Type-aware linting is powered by `typescript-go`. - TypeScript **7.0+** is required -- Some legacy `tsconfig` options are not supported +- Some legacy `tsconfig` options are not supported (like `baseUrl` in `tsconfig.json`) +- If you're using config options/features that were deprecated in TypeScript 6.0 or removed in TypeScript 7.0, you'll need to migrate your codebase first - Invalid options are reported when `--type-check` is enabled +See the [TypeScript migration guide](https://github.com/microsoft/TypeScript/issues/62508#issuecomment-3348649259) for more details, and consider using [ts5to6](https://github.com/andrewbranch/ts5to6) to upgrade your tsconfig file. + ## Stability notes Type-aware linting is **alpha**: @@ -145,7 +150,9 @@ Type-aware linting is **alpha**: - Very large codebases may encounter high memory usage - Performance continues to improve -## Performance and debugging +## Troubleshooting + +### Performance and debugging If type-aware linting is slow or uses excessive memory: @@ -163,20 +170,20 @@ OXC_LOG=debug oxlint --type-aware Example output (showing key timing milestones): ``` -2025/01/01 12:00:00.000000 Starting tsgolint -2025/01/01 12:00:00.001000 Starting to assign files to programs. Total files: 259 -2025/01/01 12:00:01.000000 Done assigning files to programs. Total programs: 8. Unmatched files: 75 -2025/01/01 12:00:01.001000 Starting linter with 12 workers -2025/01/01 12:00:01.001000 Workload distribution: 8 programs -2025/01/01 12:00:01.002000 [1/8] Running linter on program: /path/to/project/jsconfig.json +2026/01/01 12:00:00.000000 Starting tsgolint +2026/01/01 12:00:00.001000 Starting to assign files to programs. Total files: 259 +2026/01/01 12:00:01.000000 Done assigning files to programs. Total programs: 8. Unmatched files: 75 +2026/01/01 12:00:01.001000 Starting linter with 12 workers +2026/01/01 12:00:01.001000 Workload distribution: 8 programs +2026/01/01 12:00:01.002000 [1/8] Running linter on program: /path/to/project/jsconfig.json ... -2025/01/01 12:00:01.100000 [4/8] Running linter on program: /path/to/project/tsconfig.json -2025/01/01 12:00:02.500000 Program created with 26140 source files -2025/01/01 12:00:14.000000 /path/to/project/oxlint-plugin.mts +2026/01/01 12:00:01.100000 [4/8] Running linter on program: /path/to/project/tsconfig.json +2026/01/01 12:00:02.500000 Program created with 26140 source files +2026/01/01 12:00:14.000000 /path/to/project/oxlint-plugin.mts ... -2025/01/01 12:00:14.100000 [5/8] Running linter on program: /path/to/project/apps/tsconfig.json +2026/01/01 12:00:14.100000 [5/8] Running linter on program: /path/to/project/apps/tsconfig.json ... -2025/01/01 12:00:15.000000 Linting Complete +2026/01/01 12:00:15.000000 Linting Complete Finished in 16.4s on 259 files with 161 rules using 12 threads. ```