适用于 Oxlint 与 Oxfmt 的 Oxc 优先工作流

很早之前就对 Oxc 这个项目一直保持关注，看到前段时间开始进入 1.x 版本，一直想弄一套配置，这几天终于有时间搞一下。

不过目前阶段 OXLint 还是无法完整替代 ESLint ，只能是以 OXLint 为主， ESLint 为辅，但是两者可以完美结合，对项目来说，仍然可以以一套 Lint 方案去解决代码问题， OXFmt 倒是可以完美代替 Prettier 原生规则，只是部分插件仍然需要取舍，例如 Markdown 的盘古之白格式化，我只能暂时舍弃。

由于需要两套 Lint 同时工作，所以这个配置包还没有正式定名为 oxc-config ，暂时只称之为 Integration ，一个集成方案或者说是一套工作流。

这是我在 GitHub 上发布的一个开源项目。如果它对你有帮助，欢迎前往 bassist 点一个 Star。

@bassist/oxc-integration 是一个 Oxc 优先的工作流包，适合希望现在就用上带类型提示的 oxlint.config.ts 与 oxfmt.config.ts，同时在 Oxc 能力尚未完全覆盖时保留 ESLint 兜底能力的项目。

使用方法

通常只需要四步：

安装依赖（参考：安装）
添加 oxlint.config.ts（参考：Oxlint 快速开始）
添加 oxfmt.config.ts（参考：Oxfmt 快速开始）
只有在项目需要 fallback coverage 时，再补 eslint.config.js（参考：ESLint Fallback 快速开始）

安装

如果你的项目需要 ESLint fallback，请再安装对应框架所需的 ESLint 生态依赖。

编辑器设置

oxlint / eslint 的 CLI 检查结果，与编辑器里的实时诊断并不是同一件事。

如果你希望在编码过程中就获得 Oxc 的实时 lint 提示，还需要额外安装对应的编辑器插件。否则就可能出现“执行 lint 命令时能查出错误，但编辑器里没有任何提示”的情况。

VS Code / Cursor：安装官方 oxc.oxc-vscode 扩展
其他编辑器：参考 Oxc 官方的编辑器接入文档

官方文档： https://oxc.rs/docs/guide/usage/linter/editors.html

Oxc 的编辑器扩展会通过项目本地的 oxlint --lsp 工作，因此也请确保项目的 devDependencies 里已经安装了 oxlint。

如果你使用 VS Code 或 Cursor，也可以在项目里补一个 .vscode/settings.json，让保存时修复和类型感知检查更完整：

source.fixAll.oxc 用于通过 oxc.oxc-vscode 扩展启用 Oxc 的保存时自动修复
oxc.typeAware: true 可以在 TypeScript 项目里提供类型感知诊断
如果你的项目还保留 eslint.config.js 作为 fallback layer，建议继续保留 source.fixAll.eslint
如果项目已经是纯 Oxlint 工作流，可以移除 ESLint 的保存时动作

定位

如果你需要当前稳定、完整的 ESLint 优先方案，请使用 @bassist/eslint-config
如果你想采用 Oxc 优先的工作流，请使用 @bassist/oxc-integration
可以把它理解为未来 @bassist/oxc-config 的过渡形态

工作方式

@bassist/oxc-integration 采用 Oxc-first workflow：

oxlint 是主 Linter
eslint 是兜底 Linter，用来补齐 Oxc 还没完全覆盖的规则
oxfmt 是主 Formatter

这也是为什么某些项目现在仍然会同时保留 oxlint.config.ts 和 eslint.config.js。它们不再是两个并列的主配置文件，而是：

oxlint.config.ts：主 Lint 配置
eslint.config.js：兜底 Lint 配置

在这些 fallback presets 内部，会自动接入 eslint-plugin-oxlint，用于关闭那些已经由 Oxlint 覆盖的 ESLint 重叠规则。

什么时候需要 ESLint Fallback

如果 Oxc 已经足够覆盖你的项目，可以只使用 oxlint.config.ts。如果项目仍然依赖框架或生态特定的 ESLint 能力，则再补一个 eslint.config.js。

通常可以这样理解：

base / node：很多场景只用 Oxlint 就够了
react：大多数情况下可以 Oxc 优先，但很多项目仍建议保留 ESLint fallback
vue：默认建议保留 ESLint fallback
next：默认建议保留 ESLint fallback
tailwindcss：优先使用 oxlintPresets.tailwindcss() 通过 Oxc JS plugin lint；如果项目仍需要 ESLint 专属覆盖，再补 ESLint fallback
vitest：如果你需要更完整的测试规则，建议保留 ESLint fallback

内建的 Fallback Coverage

当前 @bassist/oxc-integration 已内建这些 ESLint fallback presets：

javascript
typescript
jsx
imports
jsonc
markdown
react
tailwindcss
vue
next
vitest

当前暂不纳入这个 Oxc-first 工作流范围的内容：

lint-md
基于 Prettier 的 Markdown 内容工作流

这些能力后续可以单独作为内容层工作流再设计。

配置总览

项目类型	`oxlint.config.ts`	`eslint.config.js`	`oxfmt.config.ts`
Base TS/JS	必需	可选	必需
Node	必需	可选	必需
React	必需	推荐	必需
Vue	必需	推荐	必需
Next	必需	推荐	必需

Oxlint 快速开始

Base TS/JS

React

Vue

如果你需要官方 oxlint 类型，请直接从 oxlint 包导入，而不是从本包导入。

Oxlint 内建默认值

oxlintPresets.base() 并不是空壳，它已经内置了这个包约定的 Oxc 基线配置。

当前内建默认值包括：

plugins：typescript、oxc
categories：
- correctness: error
- suspicious: error
- pedantic: warn
- style: off
基础规则覆盖：
- typescript/no-explicit-any: off

然后更高层的 presets 会在这份基线上继续扩展：

oxlintPresets.node() 会补充 Node 运行时环境
oxlintPresets.react() 会补充 react、react-perf、jsx-a11y
oxlintPresets.tailwindcss() 会通过 Oxlint JS plugins 加载 eslint-plugin-better-tailwindcss
oxlintPresets.vue() 会补充 vue
oxlintPresets.vitest() 会补充 vitest

如何扩展 Oxlint Presets

建议先使用内建默认值，再把项目特有的差异作为额外配置传入。

可以把 presets 理解成默认基线，把额外传入的对象理解成项目级扩展层。

Tailwind CSS

Tailwind preset 会通过 Oxlint JS plugins 使用 eslint-plugin-better-tailwindcss，让 Tailwind CSS v3 和 v4 项目共用同一套 class linting 规则。

ESLint Fallback 快速开始

Vue / Next / 复杂 React 项目

如果是 Vue 项目，把 react() 换成 vue() 即可。如果是 Next 项目，请使用 next()。只有项目真的在使用 Tailwind CSS 时，才需要再加上 tailwindcss()。

Markdown 内容 lint

如果你只想为 Markdown 文件开启独立的 lint 行为，而不希望把它并入 lint-md 或基于 Prettier 的内容工作流，可以使用 markdown()。

Oxfmt 快速开始

建议优先使用带类型提示的 oxfmt.config.ts，这样配置结构会与官方 formatter API 保持一致。

如果你想覆盖默认值：

oxfmt . 会自动发现 oxfmt.config.ts，所以通常不需要额外显式传入配置路径。

如果你需要官方 formatter 类型，请直接从 oxfmt 包导入，而不是从本包导入。

推荐订阅源

程沛权 - 养了三只猫