migrate-oxlint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

This skill guides you through migrating a JavaScript/TypeScript project from ESLint to Oxlint.

本技能将指导你如何将JavaScript/TypeScript项目从ESLint迁移到Oxlint。

Overview

概述

Oxlint is a high-performance linter that implements many popular ESLint rules natively in Rust. It can be used alongside ESLint or as a full replacement.

An official migration tool is available:

@oxlint/migrate

Oxlint是一款高性能代码检查工具，它采用Rust原生实现了众多流行的ESLint规则，既可以和ESLint搭配使用，也可以完全替代ESLint。

官方提供了迁移工具：

@oxlint/migrate

Step 1: Run Automated Migration

步骤1：运行自动迁移

Run the migration tool in the project root:

bash

npx @oxlint/migrate

This reads your ESLint flat config and generates a

.oxlintrc.json

file.

在项目根目录下运行迁移工具：

bash

npx @oxlint/migrate

该工具会读取你的ESLint flat配置，生成

.oxlintrc.json

文件。

Key Options

核心选项

Option	Description
`--merge`	Merge with an existing `.oxlintrc.json` instead of overwriting
`--type-aware`	Include type-aware rules (requires running oxlint with `--type-aware` )
`--with-nursery`	Include experimental rules still under development
`--js-plugins [bool]`	Enable/disable ESLint plugin migration via `jsPlugins` (default: enabled)
`--details`	List rules that could not be migrated
`--replace-eslint-comments`	Convert `// eslint-disable` comments to `// oxlint-disable`
`--output-file <file>`	Specify output path (default: `.oxlintrc.json` )

If your ESLint config is not at the default location, pass the path explicitly:

bash

npx @oxlint/migrate ./path/to/eslint.config.js

选项	说明
`--merge`	与已有的 `.oxlintrc.json` 合并，而非覆盖
`--type-aware`	包含类型感知规则（需要搭配 `--type-aware` 参数运行oxlint）
`--with-nursery`	包含仍在开发中的实验性规则
`--js-plugins [bool]`	通过 `jsPlugins` 启用/禁用ESLint插件迁移（默认：启用）
`--details`	列出无法完成迁移的规则
`--replace-eslint-comments`	将 `// eslint-disable` 注释转换为 `// oxlint-disable`
`--output-file <file>`	指定输出路径（默认： `.oxlintrc.json` ）

如果你的ESLint配置不在默认位置，请显式传入路径：

bash

npx @oxlint/migrate ./path/to/eslint.config.js

Step 2: Review Generated Config

步骤2：检查生成的配置

After migration, review the generated

.oxlintrc.json

迁移完成后，检查生成的

.oxlintrc.json

文件。

Plugin Mapping

插件映射

The migration tool automatically maps ESLint plugins to oxlint's built-in equivalents. The following table is for reference when reviewing the generated config:

ESLint Plugin	Oxlint Plugin Name
`@typescript-eslint/eslint-plugin`	`typescript`
`eslint-plugin-react` / `eslint-plugin-react-hooks`	`react`
`eslint-plugin-import` / `eslint-plugin-import-x`	`import`
`eslint-plugin-unicorn`	`unicorn`
`eslint-plugin-jsx-a11y`	`jsx-a11y`
`eslint-plugin-react-perf`	`react-perf`
`eslint-plugin-promise`	`promise`
`eslint-plugin-jest`	`jest`
`@vitest/eslint-plugin`	`vitest`
`eslint-plugin-jsdoc`	`jsdoc`
`eslint-plugin-next`	`nextjs`
`eslint-plugin-node`	`node`
`eslint-plugin-vue`	`vue`

Default plugins (enabled when

plugins

field is omitted):

unicorn

typescript

oxc

. Setting the

plugins

array explicitly overrides these defaults.

迁移工具会自动将ESLint插件映射为oxlint内置的对应插件。下表可供你检查生成的配置时参考：

ESLint插件	Oxlint插件名称
`@typescript-eslint/eslint-plugin`	`typescript`
`eslint-plugin-react` / `eslint-plugin-react-hooks`	`react`
`eslint-plugin-import` / `eslint-plugin-import-x`	`import`
`eslint-plugin-unicorn`	`unicorn`
`eslint-plugin-jsx-a11y`	`jsx-a11y`
`eslint-plugin-react-perf`	`react-perf`
`eslint-plugin-promise`	`promise`
`eslint-plugin-jest`	`jest`
`@vitest/eslint-plugin`	`vitest`
`eslint-plugin-jsdoc`	`jsdoc`
`eslint-plugin-next`	`nextjs`
`eslint-plugin-node`	`node`
`eslint-plugin-vue`	`vue`

默认插件（省略

plugins

字段时自动启用）：

unicorn

、

typescript

、

oxc

。显式设置

plugins

数组会覆盖这些默认值。

Rule Categories

规则分类

Oxlint groups rules into categories for bulk configuration:

json

{
  "categories": {
    "correctness": "warn",
    "suspicious": "warn"
  }
}

Available categories:

correctness

(default: enabled),

suspicious

pedantic

perf

style

restriction

nursery

Individual rule settings in

rules

override category settings.

Oxlint将规则归类到不同分类中，方便批量配置：

json

{
  "categories": {
    "correctness": "warn",
    "suspicious": "warn"
  }
}

可用分类：

correctness

（默认：启用）、

suspicious

、

pedantic

、

perf

、

style

、

restriction

、

nursery

。

rules

中单独设置的规则优先级高于分类设置。

Check Unmigrated Rules

检查未迁移的规则

Run with

--details

to see which ESLint rules could not be migrated:

bash

npx @oxlint/migrate --details

Review the output and decide whether to keep ESLint for those rules or find oxlint alternatives.

添加

--details

参数运行可以查看哪些ESLint规则无法迁移：

bash

npx @oxlint/migrate --details

检查输出结果，决定是否为这些规则保留ESLint，或者寻找oxlint的替代方案。

Step 3: Handle Unsupported Features

步骤3：处理不支持的特性

Some features require manual attention:

Local plugins (relative path imports): Must be migrated manually to
```
jsPlugins
```
```
eslint-plugin-prettier
```
: Not supported. Use oxfmt instead
```
settings
```
in override configs: Oxlint does not support
```
settings
```
inside
```
overrides
```
blocks
ESLint v9+ plugins: Not all work with oxlint's JS Plugins API. Test with
```
--js-plugins
```

部分特性需要手动处理：

本地插件（相对路径导入）：必须手动迁移到
```
jsPlugins
```
```
eslint-plugin-prettier
```
：不支持，请改用oxfmt
覆盖配置中的
```
settings
```
：Oxlint不支持
```
overrides
```
块内的
```
settings
```
配置
ESLint v9+插件：并非所有都兼容oxlint的JS插件API，可以使用
```
--js-plugins
```
参数测试

External ESLint Plugins

外部ESLint插件

For ESLint plugins without a built-in oxlint equivalent, use the

jsPlugins

field to load them:

json

{
  "jsPlugins": ["eslint-plugin-custom"],
  "rules": {
    "custom/my-rule": "warn"
  }
}

对于没有内置oxlint对应实现的ESLint插件，可以使用

jsPlugins

字段加载：

json

{
  "jsPlugins": ["eslint-plugin-custom"],
  "rules": {
    "custom/my-rule": "warn"
  }
}

Step 4: Update CI and Scripts

步骤4：更新CI和脚本

Replace ESLint commands with oxlint. Path arguments are optional; oxlint defaults to the current working directory.

bash

undefined

将ESLint命令替换为oxlint。路径参数是可选的，oxlint默认扫描当前工作目录。

bash

undefined

Before

迁移前

npx eslint src/ npx eslint --fix src/

After

迁移后

npx oxlint@latest npx oxlint@latest --fix

undefined

npx oxlint@latest npx oxlint@latest --fix

undefined

Common CLI Options

常用CLI选项对比

ESLint	oxlint
`eslint .`	`oxlint` (default: cwd)
`eslint src/`	`oxlint src/`
`eslint --fix`	`oxlint --fix`
`eslint --max-warnings 0`	`oxlint --deny-warnings` or `--max-warnings 0`
`eslint --format json`	`oxlint --format json`
`eslint -c config.json`	`oxlint --config config.json`

Additional oxlint options:

```
--type-aware
```
: Enable rules requiring TypeScript type information
```
--tsconfig <path>
```
: Specify tsconfig.json path for type-aware linting

ESLint	oxlint
`eslint .`	`oxlint` （默认：当前工作目录）
`eslint src/`	`oxlint src/`
`eslint --fix`	`oxlint --fix`
`eslint --max-warnings 0`	`oxlint --deny-warnings` 或 `--max-warnings 0`
`eslint --format json`	`oxlint --format json`
`eslint -c config.json`	`oxlint --config config.json`

oxlint的额外选项：

```
--type-aware
```
：启用需要TypeScript类型信息的规则
```
--tsconfig <path>
```
：为类型感知检查指定tsconfig.json路径

Tips

小贴士

Start gradually: Enable
```
correctness
```
rules first (the default), then progressively add
```
suspicious
```
,
```
pedantic
```
, etc.
Run alongside ESLint: Oxlint is designed to complement ESLint during migration. You can run both until all rules are covered.
Disable comments work:
```
// eslint-disable
```
and
```
// eslint-disable-next-line
```
comments are supported by oxlint. Use
```
--replace-eslint-comments
```
to convert them to
```
// oxlint-disable
```
if desired.
List available rules: Run
```
npx oxlint@latest --rules
```
to see all supported rules.

Schema support: Add

"$schema": "./node_modules/oxlint/configuration_schema.json"

.oxlintrc.json

for editor autocompletion.

Output formats:

default

stylish

json

github

gitlab

junit

checkstyle

unix

逐步迁移：先启用
```
correctness
```
规则（默认开启），再逐步添加
```
suspicious
```
、
```
pedantic
```
等分类的规则
可与ESLint并行运行：Oxlint设计为在迁移期间可以和ESLint互补使用，你可以同时运行两者，直到所有规则都完成覆盖
禁用注释兼容：oxlint支持
```
// eslint-disable
```
和
```
// eslint-disable-next-line
```
注释，如果你需要的话可以使用
```
--replace-eslint-comments
```
参数将它们转换为
```
// oxlint-disable
```
查看可用规则：运行
```
npx oxlint@latest --rules
```
可以查看所有支持的规则

配置Schema支持：在

.oxlintrc.json

中添加

"$schema": "./node_modules/oxlint/configuration_schema.json"

可以获得编辑器自动补全能力

输出格式：支持

default

、

stylish

、

json

、

github

、

gitlab

、

junit

、

checkstyle

、

unix

migrate-oxlint

Original

Translation

Overview

概述

Step 1: Run Automated Migration

步骤1：运行自动迁移

Key Options

核心选项

Step 2: Review Generated Config

步骤2：检查生成的配置

Plugin Mapping

插件映射

Rule Categories

规则分类

Check Unmigrated Rules

检查未迁移的规则

Step 3: Handle Unsupported Features

步骤3：处理不支持的特性

External ESLint Plugins

外部ESLint插件

Step 4: Update CI and Scripts

步骤4：更新CI和脚本

Before

迁移前

After

迁移后

Common CLI Options

常用CLI选项对比

Tips

小贴士

References

参考资料