ts-starter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript Starter

TypeScript 项目初始化配置

Automatically configure linting, formatting, testing, and compiler defaults for TypeScript projects.

自动为TypeScript项目配置代码检查、格式化、测试及编译器默认设置。

Workflow

工作流程

Detect package manager
- Prefer
```
pnpm
```
  when no lockfile exists.
- If lockfile exists, keep the existing manager.
- Detection order:
  1. ```
  pnpm-lock.yaml
```
  ->
```
  pnpm
```
2. ```
package-lock.json
```
    ->
```
npm
```
  3. ```
  yarn.lock
```
  ->
```
  yarn
```
4. ```
bun.lock
```
    or
```
bun.lockb
```
    ->
```
bun
```
- Ask the user only when detection is ambiguous.
Detect project kind
- Classify as
```
frontend
```
  ,
```
node-app
```
  , or
```
library
```
  .
- Use existing files (
```
vite.config.*
```
  , framework deps, publish fields, entry points) for detection.
- Ask the user when the project kind is unclear.
Install baseline dependencies
- Install as dev dependencies:
```
typescript
```
  ,
```
@types/node
```
  ,
```
@biomejs/biome
```
  ,
```
vitest
```
  .
- Use package-manager-specific commands from references/environment-setup.md.
Apply TypeScript configuration
- Create or update
```
tsconfig.json
```
  with strict-and-safety defaults.
- Keep ESM defaults.
- Preserve existing options whenever possible and patch only missing required fields.
- Reference: references/config-examples.md
- Template: assets/tsconfig.json.template
Apply Biome configuration
- Create or update
```
biome.json
```
  .
- Add
```
lint
```
  ,
```
lint:fix
```
  , and
```
format
```
  scripts in
```
package.json
```
  if missing.
- Keep existing scripts and merge safely.
- Reference: references/config-examples.md
- Template: assets/biome.json.template
Apply Vitest configuration
- Create or update
```
vitest.config.ts
```
  and test scripts.
- Use Vitest as the default runner for all project kinds in this skill version.
- Reference: references/config-examples.md
- Template: assets/vitest.config.ts.template
Optional VSCode settings
- Ask whether to add
```
.vscode/settings.json
```
  .
- Reference: references/vscode-settings.md
- Template: assets/.vscode-settings.json.template
Optional Git hooks
- Ask whether to set up Husky + lint-staged.
- Configure pre-commit for lint and typecheck (test optional).
- Reference: references/git-hooks-setup.md
- Template: assets/.husky-pre-commit.template
Update ignore rules
- Create or patch
```
.gitignore
```
  for common TypeScript/Node artifacts.
- Template: assets/.gitignore.template
Run smoke validation

Run
```
typecheck
```
,
```
lint
```
, and
```
test
```
once after setup.
Keep commands package-manager-specific.

检测包管理器
- 当不存在锁文件时，优先使用
```
pnpm
```
  。
- 若存在锁文件，则保留现有管理器。
- 检测顺序：
  1. ```
  pnpm-lock.yaml
```
  →
```
  pnpm
```
2. ```
package-lock.json
```
    →
```
npm
```
  3. ```
  yarn.lock
```
  →
```
  yarn
```
4. ```
bun.lock
```
    或
```
bun.lockb
```
    →
```
bun
```
- 仅当检测结果不明确时，才询问用户。
检测项目类型
- 分类为
```
frontend
```
  、
```
node-app
```
  或
```
library
```
  。
- 利用现有文件（
```
vite.config.*
```
  、框架依赖、发布字段、入口文件）进行检测。
- 当项目类型不明确时，询问用户。
安装基础依赖
- 安装开发依赖：
```
typescript
```
  、
```
@types/node
```
  、
```
@biomejs/biome
```
  、
```
vitest
```
  。
- 使用references/environment-setup.md中包管理器专属的命令。
应用TypeScript配置
- 创建或更新
```
tsconfig.json
```
  ，启用严格安全的默认设置。
- 保留ESM默认配置。
- 尽可能保留现有配置项，仅补充缺失的必填字段。
- 参考文档：references/config-examples.md
- 模板：assets/tsconfig.json.template
应用Biome配置
- 创建或更新
```
biome.json
```
  。
- 若
```
package.json
```
  中缺少
```
lint
```
  、
```
lint:fix
```
  和
```
format
```
  脚本，则添加这些脚本。
- 保留现有脚本并安全合并。
- 参考文档：references/config-examples.md
- 模板：assets/biome.json.template
应用Vitest配置
- 创建或更新
```
vitest.config.ts
```
  及测试脚本。
- 在当前版本的工具中，所有类型的项目默认使用Vitest作为测试运行器。
- 参考文档：references/config-examples.md
- 模板：assets/vitest.config.ts.template
可选VSCode设置
- 询问是否添加
```
.vscode/settings.json
```
  。
- 参考文档：references/vscode-settings.md
- 模板：assets/.vscode-settings.json.template
可选Git钩子
- 询问是否设置Husky + lint-staged。
- 配置pre-commit钩子用于代码检查和类型校验（测试为可选）。
- 参考文档：references/git-hooks-setup.md
- 模板：assets/.husky-pre-commit.template
更新忽略规则
- 创建或修补
```
.gitignore
```
  ，添加TypeScript/Node项目的常见产物忽略规则。
- 模板：assets/.gitignore.template
运行冒烟验证
- 完成设置后，运行一次
```
typecheck
```
  、
```
lint
```
  和
```
test
```
  命令。
- 使用与包管理器对应的命令。

Principles

设计原则

Config-only: Do not scaffold framework applications by default.
Command-first: Prefer commands over manual editing when possible.
Idempotent updates: Re-running setup must not duplicate scripts or corrupt config.
Preserve existing intent: Merge with current project configuration and patch only required pieces.

仅配置不搭建：默认不搭建框架应用。
优先命令行：尽可能使用命令行而非手动编辑。
幂等更新：重复运行设置不会导致脚本重复或配置损坏。
保留现有配置意图：与当前项目配置合并，仅修补必填部分。

Internal Contracts

内部约定

project_kind

frontend | node-app | library

```
package_manager
```
:
```
pnpm | npm | yarn | bun
```

project_kind

frontend | node-app | library

```
package_manager
```
:
```
pnpm | npm | yarn | bun
```

References

参考文档

Environment setup: references/environment-setup.md
Configuration examples: references/config-examples.md
Git hooks setup: references/git-hooks-setup.md
VSCode settings: references/vscode-settings.md

环境设置：references/environment-setup.md
配置示例：references/config-examples.md
Git钩子设置：references/git-hooks-setup.md
VSCode设置：references/vscode-settings.md