javascript-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

JavaScript/Node.js Conventions

JavaScript/Node.js 开发约定

Apply these conventions when working on JavaScript or Node.js files or projects.

在处理 JavaScript 或 Node.js 相关文件或项目时遵循以下约定。

Dispatch

触发规则

$ARGUMENTS	Action
Active (auto-invoked when working on JS/TS files)	Apply all conventions below
Empty	Display convention summary
`check`	Verify package manager compliance only

$ARGUMENTS	操作
Active（处理 JS/TS 文件时自动触发）	应用以下所有约定
Empty	展示约定摘要
`check`	仅验证包管理器合规性

References

参考文档

File	Purpose
`references/edge-cases.md`	Repo-specific exceptions and edge cases

文件	用途
`references/edge-cases.md`	仓库特定的例外情况和边界场景

Package Management

包管理

Use
```
pnpm
```
for all Node.js package management
Do not use
```
npm
```
or
```
yarn
```
unless the project explicitly requires them

Commands:

pnpm install

pnpm add <pkg>

pnpm run <script>

pnpm exec <cmd>

Always commit
```
pnpm-lock.yaml
```
-- never
```
.gitignore
```
it
Run
```
pnpm install --frozen-lockfile
```
in CI environments

所有 Node.js 包管理统一使用
```
pnpm
```
除非项目明确要求，否则不要使用
```
npm
```
或
```
yarn
```

常用命令：

pnpm install

、

pnpm add <pkg>

、

pnpm run <script>

、

pnpm exec <cmd>

始终提交
```
pnpm-lock.yaml
```
文件，绝对不要将其加入
```
.gitignore
```
在 CI 环境中执行
```
pnpm install --frozen-lockfile
```

Monorepo Conventions

Monorepo 约定

Use
```
pnpm
```
workspaces for multi-package repositories
Define workspaces in
```
pnpm-workspace.yaml
```
at the repo root
Use
```
pnpm -r
```
or
```
pnpm --filter <pkg>
```
for targeted operations
Hoist shared dependencies to the root where possible

多包仓库使用
```
pnpm
```
workspaces 功能
在仓库根目录的
```
pnpm-workspace.yaml
```
中定义 workspace 配置
执行定向操作时使用
```
pnpm -r
```
或
```
pnpm --filter <pkg>
```
尽可能将共享依赖提升到根目录

Lockfile Handling

Lockfile 处理

Commit lockfiles to version control
Use
```
--frozen-lockfile
```
in CI to prevent drift
When migrating from npm/yarn, delete the old lockfile and run
```
pnpm import
```
or
```
pnpm install
```

将 lockfile 提交到版本控制系统
在 CI 中使用
```
--frozen-lockfile
```
参数避免依赖版本漂移
从 npm/yarn 迁移时，删除旧的 lockfile 后执行
```
pnpm import
```
或
```
pnpm install
```

Tooling Preferences

工具偏好

Purpose	Tool
Package manager	`pnpm`
Bundler	`vite` or `esbuild`
Linting	`eslint`
Formatting	`prettier`
Testing	`vitest` or framework-native runner
Type checking	`tsc --noEmit`

用途	工具
包管理器	`pnpm`
打包工具	`vite` 或 `esbuild`
代码检查	`eslint`
格式化	`prettier`
测试	`vitest` 或框架原生运行器
类型检查	`tsc --noEmit`

Critical Rules

关键规则

Always use
```
pnpm
```
unless an existing lockfile or CI config mandates otherwise
Never mix package managers in the same project (no
```
npm install
```
alongside
```
pnpm
```
)
Commit
```
pnpm-lock.yaml
```
to version control in every project
Run
```
pnpm install --frozen-lockfile
```
in CI -- never allow lockfile mutation
Check
```
references/edge-cases.md
```
before breaking any convention
Use
```
pnpm exec
```
instead of
```
npx
```
for running local binaries

Canonical terms (use these exactly):

```
pnpm
```
-- the required package manager (not npm, not yarn)
```
lockfile
```
--
```
pnpm-lock.yaml
```
specifically
```
workspace
```
-- pnpm workspace for monorepo packages
```
frozen-lockfile
```
-- CI mode that prevents lockfile changes

除非现有 lockfile 或 CI 配置另有要求，否则始终使用
```
pnpm
```
同一个项目中绝对不要混用包管理器（不要同时使用
```
npm install
```
和
```
pnpm
```
）
所有项目都必须将
```
pnpm-lock.yaml
```
提交到版本控制
CI 中执行
```
pnpm install --frozen-lockfile
```
，绝对不允许修改 lockfile
打破任何约定前请先查看
```
references/edge-cases.md
```
运行本地二进制文件时使用
```
pnpm exec
```
而不是
```
npx
```

规范术语（请严格按照以下表述使用）：

```
pnpm
```
：强制要求使用的包管理器（不可用 npm、yarn 指代）
```
lockfile
```
：特指
```
pnpm-lock.yaml
```
```
workspace
```
：用于 monorepo 包管理的 pnpm workspace
```
frozen-lockfile
```
：禁止修改 lockfile 的 CI 运行模式