antfu

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Coding Practices

编码实践

Code Organization

代码组织

Single responsibility: Each source file should have a clear, focused scope/purpose
Split large files: Break files when they become large or handle too many concerns
Type separation: Always separate types and interfaces into
```
types.ts
```
or
```
types/*.ts
```
Constants extraction: Move constants to a dedicated
```
constants.ts
```
file

单一职责：每个源文件应具备清晰、明确的范围与用途
拆分大文件：当文件过大或涵盖过多职责时进行拆分
类型分离：始终将类型与接口分离到
```
types.ts
```
或
```
types/*.ts
```
文件中
常量提取：将常量移至专用的
```
constants.ts
```
文件

Runtime Environment

运行时环境

Prefer isomorphic code: Write runtime-agnostic code that works in Node, browser, and workers whenever possible
Clear runtime indicators: When code is environment-specific, add a comment at the top of the file:

// @env node
// @env browser

优先同构代码：尽可能编写可在 Node、浏览器和 Worker 中运行的与运行时无关的代码
清晰的运行时标识：当代码针对特定环境时，在文件顶部添加注释：

// @env node
// @env browser

TypeScript

Explicit return types: Declare return types explicitly when possible
Avoid complex inline types: Extract complex types into dedicated
```
type
```
or
```
interface
```
declarations

显式返回类型：尽可能显式声明返回类型
避免复杂内联类型：将复杂类型提取为专用的
```
type
```
或
```
interface
```
声明

Comments

注释

Avoid unnecessary comments: Code should be self-explanatory
Explain "why" not "how": Comments should describe the reasoning or intent, not what the code does

避免不必要的注释：代码应具备自解释性
解释“原因”而非“方式”：注释应描述推理或意图，而非代码的执行逻辑

Testing (Vitest)

测试（Vitest）

Test files:
```
foo.ts
```
→
```
foo.test.ts
```
(same directory)
Use
```
describe
```
/
```
it
```
API (not
```
test
```
)
Use
```
toMatchSnapshot
```
for complex outputs
Use
```
toMatchFileSnapshot
```
with explicit path for language-specific snapshots

测试文件：
```
foo.ts
```
→
```
foo.test.ts
```
（同一目录）
使用
```
describe
```
/
```
it
```
API（而非
```
test
```
）
对复杂输出使用
```
toMatchSnapshot
```
对特定语言的快照，使用带明确路径的
```
toMatchFileSnapshot
```

Tooling Choices

工具选择

@antfu/ni Commands

@antfu/ni 命令

Command	Description
`ni`	Install dependencies
`ni <pkg>` / `ni -D <pkg>`	Add dependency / dev dependency
`nr <script>`	Run script
`nu`	Upgrade dependencies
`nun <pkg>`	Uninstall dependency
`nci`	Clean install ( `pnpm i --frozen-lockfile` )
`nlx <pkg>`	Execute package ( `npx` )

命令	描述
`ni`	安装依赖
`ni <pkg>` / `ni -D <pkg>`	添加依赖 / 开发依赖
`nr <script>`	运行脚本
`nu`	升级依赖
`nun <pkg>`	卸载依赖
`nci`	干净安装（ `pnpm i --frozen-lockfile` ）
`nlx <pkg>`	执行包（ `npx` ）

TypeScript Config

TypeScript 配置

json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  }
}

json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  }
}

ESLint Setup

ESLint 配置

// eslint.config.mjs
import antfu from '@antfu/eslint-config'

export default antfu()

When completing tasks, run

pnpm run lint --fix

to format the code and fix coding style.

For detailed configuration options: antfu-eslint-config

// eslint.config.mjs
import antfu from '@antfu/eslint-config'

export default antfu()

完成任务后，运行

pnpm run lint --fix

来格式化代码并修复编码风格。

如需详细配置选项：antfu-eslint-config

Git Hooks

Git 钩子

json

{
  "simple-git-hooks": {
    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
  },
  "lint-staged": { "*": "eslint --fix" },
  "scripts": {
    "prepare": "npx simple-git-hooks"
  }
}

json

{
  "simple-git-hooks": {
    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
  },
  "lint-staged": { "*": "eslint --fix" },
  "scripts": {
    "prepare": "npx simple-git-hooks"
  }
}

pnpm Catalogs

pnpm 目录

Use named catalogs in

pnpm-workspace.yaml

for version management:

Catalog	Purpose
`prod`	Production dependencies
`inlined`	Bundler-inlined dependencies
`dev`	Dev tools (linter, bundler, testing)
`frontend`	Frontend libraries

Avoid the default catalog. Catalog names can be adjusted per project needs.

使用

pnpm-workspace.yaml

中的命名目录进行版本管理：

目录	用途
`prod`	生产依赖
`inlined`	打包器内联依赖
`dev`	开发工具（代码检查器、打包器、测试工具）
`frontend`	前端库

避免使用默认目录。可根据项目需求调整目录名称。

References

参考资料

Topic	Description	Reference
ESLint Config	Framework support, formatters, rule overrides, VS Code settings	antfu-eslint-config
Project Setup	.gitignore, GitHub Actions, VS Code extensions	setting-up
App Development	Vue/Nuxt/UnoCSS conventions and patterns	app-development
Library Development	tsdown bundling, pure ESM publishing	library-development
Monorepo	pnpm workspaces, centralized alias, Turborepo	monorepo

主题	描述	参考链接
ESLint 配置	框架支持、格式化工具、规则覆盖、VS Code 设置	antfu-eslint-config
项目搭建	.gitignore、GitHub Actions、VS Code 扩展	setting-up
应用开发	Vue/Nuxt/UnoCSS 规范与模式	app-development
库开发	tsdown 打包、纯 ESM 发布	library-development
单仓多包（Monorepo）	pnpm 工作区、集中式别名、Turborepo	monorepo