stand-ts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript / JavaScript Standards

TypeScript / JavaScript 编码规范

Standards for TypeScript and JavaScript code.

TypeScript与JavaScript代码的编写规范。

Package Manager

包管理器

Prefer
```
bun
```
over
```
npm
```
Use
```
bun install
```
instead of
```
npm install
```
Use
```
bun run
```
instead of
```
npm run
```
Use
```
bunx
```
instead of
```
npx
```

优先使用
```
bun
```
而非
```
npm
```
使用
```
bun install
```
替代
```
npm install
```
使用
```
bun run
```
替代
```
npm run
```
使用
```
bunx
```
替代
```
npx
```

Strict Mode

严格模式

Enable
```
strict: true
```
in
```
tsconfig.json
```
No
```
any
```
escape hatches without justification — if unavoidable, add a comment explaining why

在
```
tsconfig.json
```
中启用
```
strict: true
```
无正当理由不得使用
```
any
```
作为“逃生舱”——若无法避免，需添加注释说明原因

Type Patterns

类型模式

Prefer
```
interface
```
for object shapes; use
```
type
```
for unions, intersections, and mapped types
Use
```
satisfies
```
over
```
as
```
for type narrowing — preserves the inferred type while validating the shape

Avoid

enum

— use

as const

objects instead:

typescript

// Good
const Status = {
  Active: "active",
  Inactive: "inactive",
} as const;
type Status = (typeof Status)[keyof typeof Status];

// Avoid
enum Status {
  Active = "active",
  Inactive = "inactive",
}

Prefer discriminated unions over optional fields for state modeling

对象结构优先使用
```
interface
```
；联合类型、交叉类型和映射类型使用
```
type
```
类型收窄优先使用
```
satisfies
```
而非
```
as
```
——在验证结构的同时保留推断类型

避免使用

enum

——改用

as const

对象：

typescript

// 推荐写法
const Status = {
  Active: "active",
  Inactive: "inactive",
} as const;
type Status = (typeof Status)[keyof typeof Status];

// 不推荐写法
enum Status {
  Active = "active",
  Inactive = "inactive",
}

状态建模优先使用可区分联合类型而非可选字段

Error Handling

错误处理

Use

unknown

in catch clauses, not

any

typescript

// Good
catch (err: unknown) {
  if (err instanceof SpecificError) { ... }
}

// Bad
catch (err: any) { ... }

Never swallow errors with empty catch blocks
Prefer typed error results (
```
Result<T, E>
```
pattern) over thrown exceptions for expected failure paths

catch语句中使用

unknown

而非

any

：

typescript

// 推荐写法
catch (err: unknown) {
  if (err instanceof SpecificError) { ... }
}

// 不推荐写法
catch (err: any) { ... }

禁止使用空catch块吞掉错误
预期失败路径优先使用带类型的错误结果（
```
Result<T, E>
```
模式）而非抛出异常

Imports

导入规则

Use type-only imports for types:
```
import type { Foo } from "./foo";
```
Avoid barrel files (
```
index.ts
```
re-exports) in libraries — they defeat tree-shaking and obscure dependency graphs

类型仅使用类型导入：
```
import type { Foo } from "./foo";
```
库中避免使用桶文件（
```
index.ts
```
重新导出）——这会破坏摇树优化并模糊依赖关系图

Naming

命名规范

```
PascalCase
```
for types, interfaces, classes, and React components
```
camelCase
```
for variables, functions, and methods
```
UPPER_SNAKE_CASE
```
for constants and environment variable names
Prefix boolean variables/props with
```
is
```
,
```
has
```
,
```
should
```
,
```
can
```

类型、接口、类和React组件使用
```
PascalCase
```
大驼峰命名
变量、函数和方法使用
```
camelCase
```
小驼峰命名
常量和环境变量名使用
```
UPPER_SNAKE_CASE
```
大写蛇形命名
布尔变量/属性以
```
is
```
、
```
has
```
、
```
should
```
、
```
can
```
为前缀

Formatting Rules

格式化规则

More than 1 arg/param requires a trailing comma (consistent with the
```
stand-py
```
skill)
Be explicit with named arguments in object parameters when more than 1 property

参数/形参超过1个时需添加 trailing comma（与
```
stand-py
```
技能保持一致）
对象参数包含多个属性时，显式使用命名参数

Linting

代码检查

Follow the

lint

skill for linting and formatting workflow.

遵循

lint

技能中的代码检查与格式化工作流。

Testing

测试准则

Prefer Vitest over Jest
Use test functions, not test classes
Leverage
```
describe
```
blocks for grouping, not class hierarchies
Use
```
beforeEach
```
/
```
afterEach
```
for shared setup/teardown
Use
```
it.each
```
or
```
test.each
```
for parameterized tests

typescript

// Good
describe("parseConfig", () => {
  it("returns defaults for empty input", () => {
    expect(parseConfig({})).toEqual(defaults);
  });

  it.each([
    { input: "yes", expected: true },
    { input: "no", expected: false },
  ])("parses '$input' as $expected", ({ input, expected }) => {
    expect(parseBoolean(input)).toBe(expected);
  });
});

优先使用Vitest而非Jest
使用测试函数，而非测试类
利用
```
describe
```
块进行分组，而非类层级
使用
```
beforeEach
```
/
```
afterEach
```
处理共享的初始化/清理逻辑
使用
```
it.each
```
或
```
test.each
```
实现参数化测试

typescript

// 推荐写法
describe("parseConfig", () => {
  it("returns defaults for empty input", () => {
    expect(parseConfig({})).toEqual(defaults);
  });

  it.each([
    { input: "yes", expected: true },
    { input: "no", expected: false },
  ])("parses '$input' as $expected", ({ input, expected }) => {
    expect(parseBoolean(input)).toBe(expected);
  });
});

React

React 约定

When working in React codebases:

Function components only — no class components
Prefer hooks over HOCs and render props
Named exports for components (no
```
export default
```
)
Co-locate component, styles, and tests in the same directory
Extract custom hooks when logic is reused across components

在React代码库中开发时：

仅使用函数组件——禁止使用类组件
优先使用Hooks而非高阶组件（HOC）和渲染属性
组件使用命名导出（不使用
```
export default
```
）
将组件、样式和测试放在同一目录下
当逻辑在多个组件间复用，提取自定义Hooks