use-vp-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use Liangmi VP Config

使用 Liangmi VP Config

Configure projects with

@liangmi/vp-config

, an opinionated preset for Vite+, the united JavaScript toolchain. Treat Vite+ as distinct from Vite.

使用

@liangmi/vp-config

配置项目。它是一套面向 Vite+ 的强约定预设，而 Vite+ 是统一的 JavaScript 工具链。请将 Vite+ 与 Vite 视为不同工具。

Inspect the project

检查项目

Before editing:

Read the repository's
```
AGENTS.md
```
and existing
```
vite.config.ts
```
.
Inspect
```
package.json
```
, source entry points, workspace layout, and browser or Node.js signals.
Check local Vite+ documentation in
```
node_modules/vite-plus/docs
```
when an option is uncertain. Use https://viteplus.dev/guide/ only when local docs are unavailable or outdated.
Preserve project-specific overrides instead of replacing them blindly.

编辑前：

阅读仓库的
```
AGENTS.md
```
和现有的
```
vite.config.ts
```
。
检查
```
package.json
```
、源码入口、工作区布局，以及浏览器端或 Node.js 端的使用信号。
如果不确定某个选项，请查阅
```
node_modules/vite-plus/docs
```
中的本地 Vite+ 文档。仅当本地文档不可用或已过期时，才使用 https://viteplus.dev/guide/。
保留项目特定的覆盖配置，不要盲目替换。

Select a preset

选择预设

Choose one category for each

vite.config.ts

Category	Use for	Included parts
`base`	Workspace roots and projects without a clearer role	`fmt` , `lint` , `run` , `staged`
`cli`	Node.js CLI, TUI, React Ink, or Vue TUI projects	`fmt` , `lint` , `pack` , `run` , `staged`
`lib`	Published or reusable libraries	`fmt` , `lint` , `pack` , `run` , `staged`
`website`	Browser applications and websites	`fmt` , `lint` , `run` , `staged`

In a monorepo, use

base

at the workspace root and choose

cli

lib

, or

website

for member projects. Do not mix library and website signals in one project.

Treat

website

as experimental. It supports browser and component linting, but Vue template linting depends on improved upstream Oxlint support.

为每个

vite.config.ts

选择一个类别：

类别	适用场景	包含的部件
`base`	工作区根目录，以及没有更明确角色的项目	`fmt` 、 `lint` 、 `run` 、 `staged`
`cli`	Node.js CLI、TUI、React Ink 或 Vue TUI 项目	`fmt` 、 `lint` 、 `pack` 、 `run` 、 `staged`
`lib`	已发布或可复用的库	`fmt` 、 `lint` 、 `pack` 、 `run` 、 `staged`
`website`	浏览器应用和网站	`fmt` 、 `lint` 、 `run` 、 `staged`

在 monorepo 中，工作区根目录使用

base

，成员项目则选择

cli

、

lib

或

website

。不要在同一个项目中混用库和网站信号。

将

website

视为实验性功能。它支持浏览器代码和组件的 lint，但 Vue 模板 lint 依赖上游 Oxlint 支持的改进。

Install with Vite+

使用 Vite+ 安装

Use Vite+ for package management:

bash

vp install -D @liangmi/vp-config

Do not use

npm

pnpm

directly when the project is managed by Vite+.

This preset requires

vite-plus@1.0.0-rc.1

. Align the installed version with the preset's peer dependency; keep any

vite

alias to

@voidzero-dev/vite-plus-core

on the same version.

使用 Vite+ 进行包管理：

bash

vp install -D @liangmi/vp-config

当项目由 Vite+ 管理时，不要直接使用

npm

或

pnpm

。

此预设要求

vite-plus@1.0.0-rc.1

。安装版本应与预设的 peer dependency 保持一致；如果保留了指向

@voidzero-dev/vite-plus-core

的

vite

别名，也应使用相同版本。

Configure

vite.config.ts

配置

vite.config.ts

Wrap the configuration with the selected named export:

typescript

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

export default lib({
  pack: {
    entry: './src/index.ts'
  }
})

The wrapper accepts the same object, function, or promise shapes as Vite+'s

defineConfig

. User values deeply override the preset while untouched nested defaults remain enabled.

For

lib

and

cli

, define

pack.entry

explicitly from the project's real source entry points. The preset cannot infer the package's intended public entries.

Only select parts provided by the chosen category. Do not import a preset outside

vite.config.ts

Since we already use vp config preset, most of the config items can be omiited. For example, we do not need to define

lint

staged

, and

fmt

config most of the time,

dts

generation,

fixedExtendions

export

generation or

minify

pack

are also set by default. If you are doing migration works, please handle them as well.

使用选定的命名导出包装配置：

typescript

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

export default lib({
  pack: {
    entry: './src/index.ts'
  }
})

该 wrapper 接受与 Vite+ 的

defineConfig

相同的对象、函数或 Promise 形态。用户提供的值会深度覆盖预设，而未修改的嵌套默认值仍保持启用。

对于

lib

和

cli

，应根据项目真实的源码入口显式定义

pack.entry

。预设无法推断包预期的公共入口。

仅使用所选类别提供的部件。不要在

vite.config.ts

之外导入 preset。

由于已经使用 vp config preset，大多数配置项都可以省略。例如，通常不需要定义

lint

、

staged

和

fmt

配置；

pack

中的

dts

生成、

fixedExtendions

、

export

生成和

minify

也已默认设置。如果正在进行迁移，也请一并处理这些配置。

Work with preset defaults

使用预设默认值

Assume these defaults unless the project explicitly overrides them:

Linting uses strict, type-aware Oxlint with type checking and warnings denied. Do not add a separate
```
tsc
```
check solely for type checking.
Style rules are explicitly allowlisted to keep lint behavior stable across Oxlint upgrades. New upstream style rules stay disabled until they are reviewed and added.
```
console.log
```
is rejected except in the
```
cli
```
category and Node.js script overrides.
Formatting uses Oxfmt with single quotes, no semicolons, no unnecessary trailing commas, sorted imports, and sorted
```
package.json
```
fields.
```
lib
```
packaging generates declarations with
```
dts.generator: 'tsgo'
```
and package exports with fixed extensions.
```
cli
```
packaging targets Node.js, minifies, strips
```
node:
```
prefixes, and disables declaration generation.
Staged files run
```
vp check --fix
```
.

Put task cache options (

input

output

env

, and

untrackedEnv

) inside

run.tasks.<name>.cache

Use the generated cached tasks when suitable:

Task	Underlying command
`cbuild`	`vp build`
`cpack`	`vp pack`
`clint`	`vp lint`
`cfmt`	`vp fmt`
`cformat`	`vp format`
`ccheck`	`vp check`
`ctest`	`vp test`

Run them with

vp run <task>

vpr <task>

. Package scripts may call them, for example

"build": "vp run cpack"

. If there is existing scripts calling

vp <command>

inside package.json, you are supposed to change them to

vp run c<xxx>

(Only for commands listed above.).

除非项目明确覆盖，否则应使用以下默认值：

Lint 使用严格且类型感知的 Oxlint，启用类型检查并禁止警告。不要仅为类型检查而额外添加
```
tsc
```
检查。
样式规则采用显式允许列表，以保持 lint 行为在 Oxlint 升级前后保持稳定。新的上游样式规则在经过审查并加入允许列表前保持禁用。
除
```
cli
```
类别和 Node.js 脚本覆盖配置外，不允许使用
```
console.log
```
。
格式化使用 Oxfmt，采用单引号、不使用分号、不添加不必要的尾随逗号，并排序 imports 和
```
package.json
```
字段。
```
lib
```
打包通过
```
dts.generator: 'tsgo'
```
生成类型声明，并生成使用固定扩展名的 package exports。
```
cli
```
打包以 Node.js 为目标，执行压缩、去除
```
node:
```
前缀，并禁用类型声明生成。
已暂存的文件会运行
```
vp check --fix
```
。

将任务缓存选项（

input

、

output

、

env

和

untrackedEnv

）放在

run.tasks.<name>.cache

中。

适用时，使用以下已生成的缓存任务：

任务	底层命令
`cbuild`	`vp build`
`cpack`	`vp pack`
`clint`	`vp lint`
`cfmt`	`vp fmt`
`cformat`	`vp format`
`ccheck`	`vp check`
`ctest`	`vp test`

通过

vp run <task>

或

vpr <task>

运行它们。Package scripts 也可以调用这些任务，例如

"build": "vp run cpack"

。如果

package.json

中已有脚本调用

vp <command>

，应将其改为

vp run <c<xxx>>

（仅限上述列出的命令）。

Migration

迁移

@liangmi/vp-config

has a stricter ruleset, to make the linting pass after migration, you need to change runtime code to fix linting errors.

If you meet cases that can't fix easily, we prefer

// oxlint-disable-xxxx

than disabling one rules global in

vite.config.ts

@liangmi/vp-config

使用更严格的规则集。为了让迁移后的 lint 通过，需要修改运行时代码以修复 lint 错误。

如果遇到难以修复的情况，我们更倾向于使用

// oxlint-disable-xxxx

，而不是在

vite.config.ts

中全局禁用某条规则。

Validate changes

验证更改

After editing:

Run
```
vp config
```
when commit-hook configuration needs to be installed or refreshed.
Run
```
vp check
```
.
Run the relevant build, package, or test task for the changed project.
Fix preset-plugin errors rather than disabling them. They detect orphan configs, imports outside
```
vite.config.ts
```
, missing preset wrappers, improper root or project categories, and mixed library and website signals.

编辑后：

需要安装或刷新 commit hook 配置时，运行
```
vp config
```
。
运行
```
vp check
```
。
针对发生更改的项目，运行相关的构建、打包或测试任务。
修复 preset 插件报告的错误，而不是禁用这些检查。它们能够检测孤立配置、
```
vite.config.ts
```
之外的导入、缺失的 preset wrapper、不正确的根项目或项目类别，以及库与网站信号混用。