use-vp-config

使用 @liangmi/vp-config

@liangmi/vp-config 导出一个函数 liangmi()，用于 vite.config.ts。它会读取已提交的文件（package.json、tsconfig.json、index.html、工作区清单），判断每个包的项目类型，并生成用于 lint、fmt、pack、test、run 和 staged 的 Vite+ 配置。用户配置会合并到预设配置之上。

因此，大部分工作并不是编写配置，而是让已提交的文件准确描述项目，然后只编写与预设不同的配置。

需要 [email protected] 或更高版本。Vite+ 文档：node_modules/vite-plus/docs 或 https://viteplus.dev/guide/。

如何检测项目

每个项目都会获得一些特征。每项特征都来自已提交的文件：

特征	来源	变更
lib	package.json 中的 exports	pack：通过 tsgo 生成 .d.ts、固定扩展名、优化 exports
cli	package.json 中的 bin	pack：Node 目标、压缩。lint：允许使用 console、process.exit
node	package.json 中的 bin，或 tsconfig types 中的 "node"	lint：Node 全局变量和规则。test：node 环境
browser	与 package.json 同目录的 index.html，或 tsconfig lib 中的 DOM	lint：浏览器规则。test：若已安装则使用 happy-dom / jsdom
react、vue、tailwindcss	package.json 中的任意依赖字段	lint：组件规则。fmt：JSX 引号、类名排序

node 和 browser 相互独立。一个项目可以同时具备两者，也可以两者都不具备（此时不会设置 test 环境，也不会启用运行时规则）。

如果某项特征有误，请先修正源文件：在 tsconfig.json 中添加 "types": ["node"]，在 package.json 中添加 exports 或 bin，以此类推。vp pack 不会创建 exports 或 bin，因此必须将它们提交到版本库。只有在修正文件并不合理时，才使用 .option()（见 API）。

只会读取项目目录中的 tsconfig.json（以及它的 extends 链）。仅在 tsconfig.app.json 或类似文件中设置的内容不会被识别。

配置放在哪里

Vite+ 只会从工作区根目录读取 lint 和 fmt。此预设遵循以下规则：

vite.config.ts 位置	生成内容
单包仓库	全部内容
工作区根目录	lint、fmt、staged、run，并为每个成员设置专属覆盖项
工作区成员	该成员的 pack、test、run

工作区根目录是包含 pnpm-workspace.yaml 或 package.json 中 workspaces 的目录。在根目录配置和每个成员配置中都使用 liangmi()。

在成员配置中传入 lint 或 fmt，或在其中串联 lint 方法，都会抛出错误。请在根目录配置中设置成员专属的 lint 和 fmt 变更，并使用相对于工作区根目录的 files glob（例如 packages/cli/**）。

迁移现有项目

1. 先切换到 Vite+。 如果项目尚未使用 Vite+，请在工作区根目录运行 vp migrate，并按照 node_modules/vite-plus/docs/guide/migrate.md 操作。不要手动移植 ESLint、Prettier、tsup 或 Vitest 配置。Vite+ 会处理这些配置。
2. 在工作区根目录安装： vp add -D @liangmi/vp-config。工作区成员会从根目录解析该依赖。如果工作区使用 pnpm catalog，请将其添加到 catalog 中以保持一致。
3. 核对每个项目的事实信息是否与上表一致。修正错误或缺失的 package.json 和 tsconfig.json 配置。如果意图不明确，例如某个包是否会作为库发布，请询问用户。
4. 重写每个 vite.config.ts，改用 liangmi()。只编写预设尚未涵盖的内容：
   • pack.entry 不会自动推导。请为每个 lib 或 cli 项目设置该项。
   • 删除预设已设置的 fmt 选项、lint 规则、test.environment 和 pack 默认值。保留确实不同的选项，并告知用户保留了哪些选项。
   • 将现有的 lint 对象转换为扁平配置条目（参见 Lint），而不是顶层对象。
   • 保持 vite、server、plugins 和其他应用配置不变。liangmi() 会透传这些配置。
5. 更新脚本以使用缓存任务，例如 "build": "vp run cpack"、"test": "vp run ctest"、"check": "vp run ccheck"。添加 "prepare": "vp config" 以安装提交钩子。移除单独的 tsc --noEmit 步骤，因为 lint 类型检查已涵盖这些检查。
6. 运行 vp check，并修复报告的问题。参见 修复 lint 错误。
7. 运行 vp test，并为包含这些任务的项目运行 vp pack / vp build。

创建新项目

1. 使用 vp create 脚手架创建项目（vite:library、vite:application、vite:monorepo 或框架模板）。如果不确定，请阅读 node_modules/vite-plus/docs/guide/create.md。
2. 按照迁移步骤 2 到 7 操作。创建新项目时，在搭建脚手架的过程中设置事实信息：库设置 exports，CLI 设置 bin，Node 代码设置 types: ["node"]，浏览器代码设置 lib: ["DOM", ...]。

API

import { liangmi } from '@liangmi/vp-config'

export default liangmi({
  pack: { entry: ['./src/index.ts'] }
})

• liangmi(config) 接受与 Vite+ 的 defineConfig 相同的输入：对象、promise 或 ConfigEnv 函数。它已经调用了 defineConfig，因此不要再次包装。
• 直接导出可链式调用的构建器。Vite+ 会在加载配置时解析它。
• fmt、pack、run、staged 和 test 会与预设进行深度合并。lint 是扁平配置数组，会追加在预设之后。
• .only([...parts]) 仅保留指定的预设部分。.exclude([...parts]) 会移除这些部分。部分包括：fmt、lint、pack、run、staged、test。被移除部分的用户配置仍会生效，只是不再包含该部分的预设。
• .option([{ path, ...traits }]) 在根配置中声明特征。path 相对于工作区根目录（根目录使用 '.'）。声明的特征会覆盖检测结果，未声明的特征仍会自动检测。不是工作区成员的路径会作为额外项目添加。在成员中调用 .option() 会抛出错误。成员会加载根配置模块，以读取其中的声明，然后再推导自己的预设。

export default liangmi().option([
  { path: 'apps/api', node: true },
  { path: 'packages/ui', browser: true, vue: true }
])

导出的类型包括 LiangmiConfig、UserConfigFunction、ConfigPart、DeclaredProject、ProjectFacts 和 ProjectTraits。

Lint

lint 是来自 oxlint-flat-config 的 ESLint 风格扁平配置数组。后面的条目会覆盖前面的条目，且不会进行深度合并。

export default liangmi({
  lint: [
    { rules: { 'no-console': 'warn' } },
    { files: ['packages/cli/**'], rules: { 'no-console': 'off' } }
  ]
})

若要修改预设条目，而不是添加新条目，请在 liangmi() 上链式调用 composer 方法：override、replace、remove、insertBefore、insertAfter、append、prepend、overrideRules 和 removeRules。这些方法会在追加用户条目后运行。

export default liangmi()
  .override('liangmi/options', { options: { typeCheck: false } })
  .remove('liangmi/style')

预设条目名称：

• liangmi/ignores、liangmi/options
• liangmi/correctness、liangmi/perf、liangmi/suspicious、liangmi/nursery：完整类别，规则名称带插件前缀，例如 eslint/no-shadow
• liangmi/restriction、liangmi/pedantic、liangmi/style：选定的规则，大多不带前缀，例如 no-console
• 按特性划分：liangmi/node、liangmi/browser、liangmi/cli、liangmi/react、liangmi/vue
• 按文件角色划分：liangmi/test、liangmi/script、liangmi/config-file

在工作区中，成员条目会包含路径，例如 liangmi/packages/cli/react。overrideRules 和 removeRules 会完全匹配规则名称，因此请使用定义该规则的条目中所写的名称。要查找该条目，请搜索 node_modules/@liangmi/vp-config/dist/index.mjs。

修复 lint 错误

该预设比较严格，并且启用了 denyWarnings，因此警告也会导致失败。迁移通常会带来大量新报告。请先修复代码。不要在未征求用户意见的情况下批量关闭规则。

• 许多报告都可以自动修复。先运行 vp check --fix，然后手动修复剩余问题。
• 相对导入需要文件扩展名（./util.ts）。TypeScript 项目需要在 tsconfig.json 中设置 allowImportingTsExtensions（并启用 noEmit），或设置 rewriteRelativeImportExtensions。
• 类会导致错误（max-classes-per-file: 0）。优先使用函数和普通对象。
• console 会导致错误，但 cli 项目和脚本文件除外。**/*.config.ts 文件允许默认导出，但不允许使用 console。
• 测试文件必须命名为 *.test.ts。*.spec.ts 文件会按测试文件进行 lint，但会因文件名而收到报告。
• 文件角色在每个项目内生效：scripts/**、script/** 和顶层的 *.ts / *.js 文件都是 Node 脚本。
• bin/** 会被忽略。
• 只有 oxlint-disable 注释才会生效。eslint-disable 注释会被忽略，因此请将现有注释转换为 oxlint-disable。未使用的禁用注释会被报告。如果禁用规则确有必要，请使用 // oxlint-disable-next-line <rule> -- <reason>。
• 类型检查会在 lint 时运行。类型错误会显示在 vp check 中。

验证结果

打印解析后的配置，以确认检测到的特性：

node -e "const c = (await import('./vite.config.ts')).default; console.log(JSON.stringify(c, null, 2))"

在要检查的配置所在目录中运行。Node 22.18+ 可以直接导入 TypeScript 配置。如果配置是函数，请使用 await c({ command: 'build', mode: 'production' })，而不是 c。检查 lint.overrides 中是否包含预期的 liangmi/<path>/<trait> 条目、test.environment 是否正确，以及 pack 是否具有 lib 或 cli 默认值。

缓存任务

每个配置都会添加以下任务。使用 vp run <task>（或 vpr <task>）运行：

任务	运行
cbuild	vp build
cpack	vp pack
clint	vp lint
cfmt	vp fmt
cformat	vp format
ccheck	vp check
ctest	vp test

在 package.json 脚本中使用这些任务，以便应用 Vite+ 任务缓存。在 run.tasks.<name>.cache 下更改缓存输入。根配置还会将 staged 设为在暂存文件上运行 vp check --fix。