@skyroc/config

概览

两种工具的接入形式不同：Oxlint 走 JSON extends（相对路径），Vitest 走 TS 模块 import（包名子路径）。

快速上手

// apps/admin/.oxlintrc.json
{ "extends": ["../../internal/config/oxlint/react.json"] }

// packages/@core/service/vitest.config.ts
import { COVERAGE_EXCLUDE, baseCoverageConfig, baseTestConfig } from '@skyroc/config/vitest';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    ...baseTestConfig,
    coverage: {
      ...baseCoverageConfig,
      exclude: [...COVERAGE_EXCLUDE, 'src/cli/**']
    }
  }
});

子入口

{
  "files": ["dist", "oxlint"],
  "exports": {
    "./oxlint/base.json": "./oxlint/base.json",
    "./oxlint/next.json": "./oxlint/next.json",
    "./oxlint/react.json": "./oxlint/react.json",
    "./package.json": "./package.json",
    "./vitest": {
      "types": "./dist/index.d.mts",
      "default": "./dist/index.mjs"
    }
  }
}

JSON 暴露源路径，TS 模块只暴露 dist（避免应用层意外编译 TS 源）。

仓库内所有 .oxlintrc.json 用的都是相对路径 ../../internal/config/oxlint/*.json——oxlint 自己解析 extends，不走 Node 的 exports 字段，所以 exports 里漏掉的 ./oxlint/react-native.json 并不影响使用。

Oxlint 预设

预设详解

base.json

类别开关是理解这份配置的前提：

{
  "categories": {
    "correctness": "off",
    "suspicious": "error"
  }
}

correctness 整类被关掉，改为在 rules 里逐条显式开启——这样规则集是白名单，升级 oxlint 时不会凭空多出一批报错。

关键规则（节选）：

jsPlugins: ["eslint-plugin-sort"] 额外接入了一组排序规则，这是仓库里最容易撞到的一类：

overrides 分四组：

TypeScript 相关的关键取舍：

react.json

在 base 之上加 react 插件。最重要的一条是禁用 useCallback：

{
  "no-restricted-imports": [
    "error",
    {
      "paths": [
        {
          "name": "react",
          "importNames": ["useCallback"],
          "message": "useCallback is forbidden — see AGENTS.md §2. Hoist the function, use a ref, or re-draw the component boundary instead."
        }
      ]
    }
  ]
}

这条规则把 AGENTS.md 的组件规范落成了 lint 错误，详见 编码规范。

其余：

**/*.jsx、**/*.tsx 的 override 里再开 react/rules-of-hooks（error）、react/exhaustive-deps（error）、react/jsx-key、react/display-name 等。

next.json

extends react，追加 jsx-a11y 与 nextjs 插件，打开整套 nextjs/* 规则（no-html-link-for-pages、no-document-import-in-page、inline-script-id 等为 error，其余多为 warn），并把 react/only-export-components 关掉——Next.js 的 page.tsx 需要同时导出 metadata、generateStaticParams。

react-native.json

extends react，主要做三件事：

• 注入 RN 全局变量：__DEV__、ErrorUtils、HermesInternal、__turboModuleProxy、nativeFabricUIManager、_WORKLET（Reanimated worklet）；
• 关掉 unicorn/no-array-reverse、unicorn/no-array-sort、react/no-unescaped-entities（RN 文本节点没有 HTML 转义问题）；
• react/exhaustive-deps 降为 warn，no-use-before-define 放开 variables（RN 里 StyleSheet.create 常写在组件下方）。

Vitest 共享配置

src/vitest/index.ts 经 tsdown 构建为 ESM，通过 @skyroc/config/vitest 引用：

import {
  COVERAGE_EXCLUDE,
  COVERAGE_PROVIDER,
  SOURCE_PATTERNS,
  TEST_ENVIRONMENT,
  TEST_PATTERNS,
  baseCoverageConfig,
  baseTestConfig
} from '@skyroc/config/vitest';

导出常量

测试文件只认 __tests__/ 目录——src/ 里的 *.test.ts 不会被匹配到。

预设对象

export const baseTestConfig: InlineConfig = {
  globals: true,
  environment: TEST_ENVIRONMENT,
  include: TEST_PATTERNS
};

export const baseCoverageConfig: CoverageOptions = {
  provider: COVERAGE_PROVIDER,
  enabled: true,
  include: SOURCE_PATTERNS,
  exclude: COVERAGE_EXCLUDE
};

baseTestConfig 不含 setupFiles，需要前置文件的包（packages/hooks、packages/@core/utils、packages/@core/state）在自己的 vitest.config.ts 里加；baseCoverageConfig 也不含 reporter，用 vitest 默认值。

仓库内实际使用

Oxlint：

docs/docs、docs/admin-docs、docs/native-ui-docs 目前是各自独立的 .oxlintrc.json，没有 extends 本包，属于待收敛项。

Vitest： 17 个子包的 vitest.config.ts 以及根 vitest.config.ts 都从 @skyroc/config/vitest 取值。根配置只复用常量（TEST_ENVIRONMENT / COVERAGE_PROVIDER / SOURCE_PATTERNS / COVERAGE_EXCLUDE），自己定义根视角的 include（packages/**/__tests__/**）、排除走 Jest 的 packages/native/**，并把覆盖率范围限定在已有测试的包上，避免无测试包刷出大量 0%。

lint 脚本：

升级影响范围

改预设会自动影响所有 extends / import 它的包，流程是：

1. 修改预设 JSON 或 vitest 常量；
2. 在仓库根跑 pnpm lint、pnpm test 确认所有包通过；
3. 一次性修完违规再提交。

规则集中带来的好处是治理简单，代价是引入新规则的成本一次性付清。

相关文档

• Lint 与格式化 —— 完整规则说明、oxfmt 与提交前检查
• 测试 —— 测试组织方式与覆盖率要求
• 编码规范 —— useCallback 禁令等规则背后的理由
• @skyroc/tsconfig —— 与之配套的 TS 编译预设

Last updated on