Lint 与格式化

概览

本项目采用 Oxc 工具链 作为核心 lint 与格式化方案：

全仓库（含 Expo 应用 apps/native-ui-playground）已统一到 Oxlint，没有任何包再跑 ESLint。eslint-plugin-sort 是唯一的例外——它通过 Oxlint 的 jsPlugins 桥接运行，不需要 ESLint 本体。

常用命令

# 全仓库 lint（通过 Turborepo 并行执行各包的 lint 脚本）
pnpm lint

# 全仓库格式化
pnpm format

# 仅检查格式（不写入，适合 CI）
pnpm format:check

Oxlint — 代码检查

工具选型理由

Oxlint 使用 Rust 编写，相较 ESLint 有 50-100 倍 的性能优势，且无需安装额外的 parser。项目通过 .oxlintrc.json 进行配置，支持根级配置继承 + 子包 override 的分层模式。

配置层级

.oxlintrc.json                          ← 根配置（所有包共享）
├── apps/*/.oxlintrc.json               ← 五个应用（+ React / Sort 插件）
├── docs/*/.oxlintrc.json               ← 各文档站（+ Next.js 插件）
├── packages/web/ui/*/.oxlintrc.json    ← shadcn / antd / compose
├── packages/web/*/.oxlintrc.json       ← admin-layouts / admin-theme / materials 等
└── packages/native/ui/.oxlintrc.json   ← Native UI

根配置插件

根 .oxlintrc.json 启用的插件：

• node — Node.js 环境规则（node/handle-callback-err、node/no-path-concat 等）
• import — 导入规范（禁止重复导入、禁止可变导出等）
• unicorn — 现代 JS 最佳实践（prefer-node-protocol、throw-new-error 等）
• typescript（通过 overrides 对 *.ts / *.tsx 启用）— 类型安全规则

子包扩展插件

Admin 应用与 UI 组件包在根配置基础上额外启用：

• react — React 规则（rules-of-hooks、exhaustive-deps、jsx-key 等）
• eslint-plugin-sort（通过 jsPlugins 桥接）— 排序规则
  • sort/destructuring-properties — 解构属性排序
  • sort/import-members — import 成员排序
  • sort/exports — export 排序
  • sort/string-enums / sort/string-unions — 枚举/联合类型成员排序
  • sort/type-properties — 类型属性排序

文档站点额外启用 nextjs（Next.js 框架规则），部分站点还开了 jsx-a11y、jsdoc / promise，以各站自己的 .oxlintrc.json 为准。

核心规则亮点

各包 lint 脚本

Oxfmt — 代码格式化

工具选型理由

Oxfmt 是 Oxc 工具链的格式化器，同样基于 Rust，性能极高。项目使用它替代了 Prettier，配置文件为根目录的 .oxfmtrc.json，全仓库共享一份配置。

格式化规则

根据 .oxfmtrc.json 的配置：

{
  "printWidth": 120,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "none",
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "avoid",
  "endOfLine": "lf",
  "singleAttributePerLine": false,
  "jsdoc": true,
  "sortImports": {
    "partitionByNewline": true,
    "newlinesBetween": false
  },
  "sortPackageJson": true
}

规则说明

忽略文件

格式化会跳过以下目录/文件：

• node_modules、dist、.turbo、.next、.cache、coverage
• pnpm-lock.yaml、routeTree.gen.ts
• .claude、.agents

EditorConfig

.editorconfig 确保不同编辑器之间的基础格式一致：

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true
quote_type = single

[*.md]
trim_trailing_whitespace = false

Turborepo 集成

turbo.json 中定义了 lint 任务：

{
  "lint": {
    "dependsOn": ["^build"],
    "outputs": []
  }
}

• dependsOn: ["^build"] — lint 任务会等待依赖包构建完成后再执行，确保类型信息可用
• outputs: [] — lint 不产生文件输出，不做缓存

格式化 (format / format:check) 直接在根 package.json 调用 oxfmt，不经过 Turborepo，因为 Oxfmt 天然支持全仓库扫描。

工具链架构图

pnpm lint
  └─ turbo run lint
       ├─ apps/*        → oxlint --fix
       ├─ packages/**   → oxlint --fix
       └─ docs/*        → oxlint

pnpm format
  └─ oxfmt (全仓库, .oxfmtrc.json)

pnpm format:check
  └─ oxfmt --check (CI 模式, 仅检查不写入)

添加新包时的 Lint 配置

1. 在新包的 package.json 中添加 "lint": "oxlint" 或 "lint": "oxlint --fix" 脚本
2. 如果新包有特殊需求（如 React、Next.js 规则），在包目录下创建 .oxlintrc.json 覆盖/扩展根配置
3. Turborepo 会自动发现并编排所有包含 lint 脚本的包

Last updated on