template-ts-node

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript Node.js Project Setup

TypeScript Node.js 项目搭建

Scaffold production-ready TypeScript Node.js projects with modern tooling and best practices. Default configuration targets single-repository, non-UI projects (libraries, CLI tools, backend services). Uses Bun for package management and Vitest for testing.

使用现代化工具和最佳实践搭建可用于生产环境的TypeScript Node.js项目。默认配置针对单仓库、非UI项目（库、CLI工具、后端服务），采用Bun进行包管理，Vitest进行测试。

Quick Reference: Configuration Files

快速参考：配置文件

File	Purpose
`package.json`	Project metadata, dependencies, and scripts
`tsconfig.json`	TypeScript compiler configuration
`biome.jsonc`	Linting and formatting rules
`justfile`	Task automation and project commands
`vitest.config.ts`	Test framework configuration
`.gitignore`	Version control exclusions
`.gitattributes`	Git line-ending and merge behavior
`.husky/`	Git hooks for pre-commit automation
`bun.lockb`	Dependency lock file (Bun)

文件名称	用途
`package.json`	项目元数据、依赖项和脚本
`tsconfig.json`	TypeScript编译器配置
`biome.jsonc`	代码检查与格式化规则
`justfile`	任务自动化与项目命令
`vitest.config.ts`	测试框架配置
`.gitignore`	版本控制忽略文件配置
`.gitattributes`	Git行尾格式与合并行为配置
`.husky/`	用于提交前自动化的Git钩子
`bun.lockb`	Bun的依赖锁定文件

Setup Workflow

搭建流程

1. Initialize Project Structure

1. 初始化项目结构

Create the project directory and initialize version control.

bash

mkdir project-name
cd project-name
git init

创建项目目录并初始化版本控制。

bash

mkdir project-name
cd project-name
git init

2. Copy Configuration Files

2. 复制配置文件

Copy all configuration files from

resources/

directory to the project root. These files are pre-configured to extend

@sablier/devkit

and follow established patterns.

Required files:

```
package.json
```
- Adapt name, description, version, and author fields

tsconfig.json

- Extends

@sablier/devkit/tsconfig/base.json

biome.jsonc

- Extends

ultracite/core

and

@sablier/devkit/biome/base

```
justfile
```
- Imports
```
@sablier/devkit/just/base.just
```
```
vitest.config.ts
```
- Test configuration
```
.gitignore
```
- Standard Node.js exclusions
```
.gitattributes
```
- Line endings and diff behavior

将

resources/

目录下的所有配置文件复制到项目根目录。这些文件已预配置为继承

@sablier/devkit

并遵循既定规范。

必填文件：

```
package.json
```
- 调整名称、描述、版本和作者字段

tsconfig.json

- 继承

@sablier/devkit/tsconfig/base.json

biome.jsonc

- 继承

ultracite/core

和

@sablier/devkit/biome/base

```
justfile
```
- 导入
```
@sablier/devkit/just/base.just
```
```
vitest.config.ts
```
- 测试框架配置
```
.gitignore
```
- 标准Node.js忽略规则
```
.gitattributes
```
- 行尾格式与差异对比行为配置

3. Install Dependencies

3. 安装依赖项

Use Bun to install project dependencies.

bash

bun install

Core dependencies:

@sablier/devkit

(from GitHub:

github:sablier-labs/devkit

)

```
typescript
```
```
vitest
```
(testing)
```
@biomejs/biome
```
(linting/formatting)
```
husky
```
(git hooks)
```
just
```
(task runner, if not globally installed)

使用Bun安装项目依赖。

bash

bun install

核心依赖：

@sablier/devkit

（GitHub地址：

github:sablier-labs/devkit

）

```
typescript
```
```
vitest
```
（测试工具）
```
@biomejs/biome
```
（代码检查/格式化工具）
```
husky
```
（Git钩子工具）
```
just
```
（任务运行器，若未全局安装）

4. Initialize Git Hooks

4. 初始化Git钩子

Set up Husky for pre-commit automation.

bash

bun run prepare

This installs git hooks that run linting and formatting checks before commits.

设置Husky以实现提交前自动化检查。

bash

bun run prepare

此命令会安装Git钩子，在提交前自动运行代码检查和格式化。

5. Create Source Structure

5. 创建源码结构

Establish the core source directory and entry point.

bash

mkdir src
touch src/index.ts

Add initial content to

src/index.ts

typescript

// -------------------------------------------------------------------------- //
//                                   EXPORTS                                  //
// -------------------------------------------------------------------------- //

export const VERSION = "0.1.0";

建立核心源码目录和入口文件。

bash

mkdir src
touch src/index.ts

在

src/index.ts

中添加初始内容：

typescript

// -------------------------------------------------------------------------- //
//                                   EXPORTS                                  //
// -------------------------------------------------------------------------- //

export const VERSION = "0.1.0";

6. Verify Setup

6. 验证搭建结果

Run full project checks to ensure configuration is correct.

bash

just full-check

This executes TypeScript compilation, linting, formatting checks, and tests.

运行完整项目检查以确保配置正确。

bash

just full-check

此命令会执行TypeScript编译、代码检查、格式化验证和测试。

Key Configuration Choices

关键配置选择

Shared Configuration via @sablier/devkit

通过@sablier/devkit共享配置

All configuration files extend the shared devkit to maintain consistency across projects. This approach centralizes common patterns and reduces per-project configuration burden.

GitHub location:

github:sablier-labs/devkit

所有配置文件都继承自共享的devkit，以保持项目间的一致性。这种方式集中了通用规范，减少了每个项目的配置工作量。

GitHub地址：

github:sablier-labs/devkit

TypeScript Configuration

TypeScript配置

Extend the base TypeScript configuration from devkit. Customize

compilerOptions

only when project-specific requirements demand it.

Example
tsconfig.json
:

json

{
  "extends": "@sablier/devkit/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Key settings (inherited from devkit):

```
strict: true
```
- Maximum type safety
```
esModuleInterop: true
```
- CommonJS/ESM compatibility
```
skipLibCheck: true
```
- Faster compilation
```
module: "ESNext"
```
- Modern module system
```
target: "ES2022"
```
- Recent language features

继承devkit中的基础TypeScript配置。仅当项目有特定需求时，才自定义

compilerOptions

。

示例
tsconfig.json
：

json

{
  "extends": "@sablier/devkit/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

从devkit继承的关键设置：

```
strict: true
```
- 最高级别类型安全
```
esModuleInterop: true
```
- CommonJS/ESM兼容性
```
skipLibCheck: true
```
- 更快的编译速度
```
module: "ESNext"
```
- 现代化模块系统
```
target: "ES2022"
```
- 支持最新语言特性

Biome Configuration

Biome配置

Extend both Ultracite core rules and Sablier devkit overrides. This provides opinionated linting and formatting with project-specific adjustments.

Example
biome.jsonc
:

jsonc

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "extends": ["ultracite/core", "@sablier/devkit/biome/base"],
  "formatter": {
    "indentStyle": "space",
    "lineWidth": 120
  }
}

Inherited behaviors:

Sorted imports and exports
Consistent naming conventions
No unused variables
Explicit function return types

同时继承Ultracite核心规则和Sablier devkit的覆盖规则。这提供了带有项目特定调整的代码检查和格式化规范。

示例
biome.jsonc
：

jsonc

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "extends": ["ultracite/core", "@sablier/devkit/biome/base"],
  "formatter": {
    "indentStyle": "space",
    "lineWidth": 120
  }
}

继承的行为：

导入和导出语句排序
一致的命名规范
禁止未使用的变量
显式函数返回类型

Just Task Runner

Just任务运行器

Import base recipes from devkit and add only project-specific tasks. The devkit provides common recipes—do not duplicate them.

Example
justfile
:

just

import "./node_modules/@sablier/devkit/just/base.just"

从devkit导入基础任务，仅添加项目特定的任务。devkit已提供通用任务，请勿重复定义。

示例
justfile
：

just

import "./node_modules/@sablier/devkit/just/base.just"

Default recipe

默认任务

default: @just --list

Project-specific recipes only

仅添加项目特定任务

[group("app")] build: na tsc


**For advanced Just CLI usage** (modules, attributes, inline scripts, conditional execution), consult the `just-cli` skill which provides comprehensive guidance on Just's advanced features.

[group("app")] build: na tsc


**关于Just CLI的高级用法**（模块、属性、内联脚本、条件执行），请参考`just-cli`技能，该技能提供了Just高级功能的全面指导。

Vitest Configuration

Vitest配置

Configure test framework with TypeScript support and coverage reporting.

Example
vitest.config.ts
:

typescript

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    environment: "node",
    coverage: {
      provider: "v8",
      reporter: ["text", "json", "html"],
    },
  },
});

配置支持TypeScript和覆盖率报告的测试框架。

示例
vitest.config.ts
：

typescript

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    environment: "node",
    coverage: {
      provider: "v8",
      reporter: ["text", "json", "html"],
    },
  },
});

Common Just Recipes

常用Just任务

Execute these commands from the project root using the

just

command.

在项目根目录使用

just

命令执行以下任务。

Recipes from @sablier/devkit

来自@sablier/devkit的任务

The devkit provides these recipes—do not redefine them:

Recipe	Alias	Description
`full-check`	`fc`	Run all code checks (biome + prettier + types)
`full-write`	`fw`	Run all code fixes
`biome-check`	`bc`	Run Biome linting and formatting checks
`biome-write`	`bw`	Apply Biome fixes
`biome-lint`	`bl`	Run Biome linter only
`type-check`	`tc`	TypeScript type checking (tsgo/tsc)
`tsc-build`	`tb`	Build with TypeScript
`prettier-check`	`pc`	Check Prettier formatting
`prettier-write`	`pw`	Apply Prettier formatting
`knip-check`	`kc`	Check for unused exports/dependencies
`knip-write`	`kw`	Fix unused exports/dependencies
`clean`		Clean .DS_Store files
`clean-modules`		Remove node_modules recursively
`install`		Install dependencies with ni

devkit已提供这些任务，请勿重新定义：

任务名称	别名	描述
`full-check`	`fc`	运行所有代码检查（biome + prettier + 类型检查）
`full-write`	`fw`	运行所有代码修复
`biome-check`	`bc`	运行Biome代码检查和格式化验证
`biome-write`	`bw`	应用Biome修复
`biome-lint`	`bl`	仅运行Biome代码检查
`type-check`	`tc`	TypeScript类型检查（tsgo/tsc）
`tsc-build`	`tb`	使用TypeScript编译
`prettier-check`	`pc`	检查Prettier格式化
`prettier-write`	`pw`	应用Prettier格式化
`knip-check`	`kc`	检查未使用的导出/依赖项
`knip-write`	`kw`	修复未使用的导出/依赖项
`clean`		清理.DS_Store文件
`clean-modules`		递归删除node_modules
`install`		使用ni安装依赖项

Project-Specific Recipes

项目特定任务

Define only what the devkit doesn't provide:

bash

just build      # Compile TypeScript (project entry point)
just dev        # Start development mode with file watching
just test       # Run tests with Vitest
just test-ui    # Run tests with Vitest UI

仅定义devkit未提供的任务：

bash

just build      # 编译TypeScript（项目入口）
just dev        # 启动开发模式并监听文件变化
just test       # 使用Vitest运行测试
just test-ui    # 使用Vitest UI运行测试

Package.json Scripts

Package.json脚本

Leave empty besides the husky setup. The

justfile

is used to run commands.

Essential scripts:

json

{
  "scripts": {
    "prepare": "husky install"
  }
}

除了husky设置外，其余留空。使用

justfile

运行命令。

必要脚本：

json

{
  "scripts": {
    "prepare": "husky install"
  }
}

Directory Structure

目录结构

Organize project files following these conventions:

project-name/
├── src/
│   ├── index.ts          # Main entry point
│   ├── lib/              # Library code
│   ├── utils/            # Utility functions
│   └── types/            # Type definitions
├── test/
│   └── index.test.ts     # Test files
├── dist/                 # Compiled output (gitignored)
├── coverage/             # Test coverage reports (gitignored)
├── node_modules/         # Dependencies (gitignored)
├── package.json
├── tsconfig.json
├── biome.jsonc
├── justfile
├── vitest.config.ts
├── .gitignore
├── .gitattributes
├── .husky/
│   └── pre-commit
├── bun.lockb
└── README.md

按照以下规范组织项目文件：

project-name/
├── src/
│   ├── index.ts          # 主入口文件
│   ├── lib/              # 库代码
│   ├── utils/            # 工具函数
│   └── types/            # 类型定义
├── test/
│   └── index.test.ts     # 测试文件
├── dist/                 # 编译输出（已加入git忽略）
├── coverage/             # 测试覆盖率报告（已加入git忽略）
├── node_modules/         # 依赖项（已加入git忽略）
├── package.json
├── tsconfig.json
├── biome.jsonc
├── justfile
├── vitest.config.ts
├── .gitignore
├── .gitattributes
├── .husky/
│   └── pre-commit
├── bun.lockb
└── README.md

Resource Files

资源文件

Copy these pre-configured files from

resources/

directory to bootstrap new projects:

File	Purpose
`package.json`	Base package.json with devDependencies (adapt name, description)
`tsconfig.json`	TypeScript configuration extending devkit
`biome.jsonc`	Linting and formatting rules
`justfile`	Project-specific recipes only (imports devkit base)
`vitest.config.ts`	Test framework setup for single repos
`vitest.shared.ts`	Shared test config for monorepos
`.prettierrc.js`	Prettier config extending devkit
`.prettierignore`	Prettier ignore patterns
`.lintstagedrc.js`	Pre-commit hook configuration
`.gitignore`	Standard Node.js exclusions

Usage: Copy files to project root, then adapt

package.json

fields (name, description, author, version).

Important: The

justfile

imports

@sablier/devkit/just/base.just

which provides common recipes. Only add project-specific recipes that aren't in the devkit.

从

resources/

目录复制以下预配置文件，以快速启动新项目：

文件名称	用途
`package.json`	包含开发依赖的基础package.json（需调整名称、描述等字段）
`tsconfig.json`	继承devkit的TypeScript配置
`biome.jsonc`	代码检查和格式化规则
`justfile`	仅包含项目特定任务（导入devkit基础任务）
`vitest.config.ts`	单仓库项目的测试框架设置
`vitest.shared.ts`	单仓库项目的共享测试配置
`.prettierrc.js`	继承devkit的Prettier配置
`.prettierignore`	Prettier忽略规则
`.lintstagedrc.js`	提交前钩子配置
`.gitignore`	标准Node.js忽略规则

使用方法： 将文件复制到项目根目录，然后调整

package.json

的字段（名称、描述、作者、版本）。

注意：

justfile

会导入

@sablier/devkit/just/base.just

，该文件提供了通用任务。仅添加devkit未包含的项目特定任务。

Best Practices

最佳实践

Dependency Management

依赖管理

Pin major versions but allow minor and patch updates:

json

{
  "dependencies": {
    "@sablier/devkit": "github:sablier-labs/devkit",
    "zod": "^3.22.0"
  }
}

Separate dev and production dependencies clearly:

Runtime code →
```
dependencies
```
Build tools, linters, test frameworks →
```
devDependencies
```

固定主版本号，但允许小版本和补丁版本更新：

json

{
  "dependencies": {
    "@sablier/devkit": "github:sablier-labs/devkit",
    "zod": "^3.22.0"
  }
}

明确区分开发依赖和生产依赖：

运行时代码 →
```
dependencies
```
构建工具、代码检查工具、测试框架 →
```
devDependencies
```

TypeScript Configuration

TypeScript配置

Enable strict mode for maximum type safety. Override specific checks only when absolutely necessary.

Use path aliases for cleaner imports:

json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

启用严格模式以获得最高类型安全性。仅在绝对必要时，才覆盖特定检查规则。

使用路径别名以简化导入：

json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

Testing Strategy

测试策略

Co-locate tests with source files or use parallel

test/

directory structure.

Name test files with

.test.ts

.spec.ts

suffix.

Write tests first for complex logic (TDD approach).

Aim for high coverage on critical paths, but don't chase 100% arbitrarily.

将测试文件与源码文件放在一起，或使用平行的

test/

目录结构。

测试文件命名使用

.test.ts

或

.spec.ts

后缀。

复杂逻辑先写测试（TDD方法）。

关键路径追求高覆盖率，但不要为了100%覆盖率而盲目编写测试。

Git Workflow

Git工作流

Commit often with descriptive messages.

Use conventional commits format:

feat:

fix:

docs:

refactor:

, etc.

Let Husky hooks catch issues before they reach the repository.

Tag releases with semantic versioning:

v1.0.0

v1.1.0

, etc.

频繁提交，并使用描述性的提交信息。

使用约定式提交格式：

feat:

、

fix:

、

docs:

、

refactor:

等。

让Husky钩子在问题提交到仓库前捕获它们。

使用语义化版本标记发布：

v1.0.0

、

v1.1.0

等。

Code Organization

代码组织

Group by feature rather than by file type when projects grow beyond simple structure.

Export from index files to create clean public APIs:

typescript

// src/lib/index.ts
export { functionA } from "./moduleA.js";
export { functionB } from "./moduleB.js";

Use barrel exports sparingly - they can impact tree-shaking.

当项目规模超出简单结构时，按功能分组，而非按文件类型。

从索引文件导出以创建清晰的公共API：

typescript

// src/lib/index.ts
export { functionA } from "./moduleA.js";
export { functionB } from "./moduleB.js";

谨慎使用桶式导出——它们可能影响Tree-shaking优化。

Next Steps After Setup

搭建完成后的下一步

Write initial code in
```
src/index.ts
```
Add first test in
```
test/index.test.ts
```
Run
just full-check
to verify everything works
Create initial commit with all scaffolding
Set up remote repository and push
Configure CI/CD using GitHub Actions or similar
Write README.md with project-specific documentation
Add LICENSE file appropriate for your use case

在
src/index.ts
中编写初始代码
在
test/index.test.ts
中添加第一个测试
运行
just full-check
以验证所有功能正常
提交所有脚手架文件的初始版本
设置远程仓库并推送代码
使用GitHub Actions或类似工具配置CI/CD
编写README.md，添加项目特定文档
添加适合项目的LICENSE文件

Reference Documentation

参考文档

For detailed guidance on specific topics, consult these reference files:

./references/adapting-project-types.md
- CLI tools, libraries, and backend services setup
./references/troubleshooting.md
- Common issues and solutions
./references/ide-ci-integration.md
- VSCode, GitHub Actions, and pre-commit setup
./references/next-ui.md
- React/Next.js UI projects
./references/monorepo.md
- Workspace and monorepo configuration

如需特定主题的详细指导，请参考以下文档：

./references/adapting-project-types.md
- CLI工具、库和后端服务的搭建指南
./references/troubleshooting.md
- 常见问题与解决方案
./references/ide-ci-integration.md
- VSCode、GitHub Actions和提交前钩子的设置
./references/next-ui.md
- React/Next.js UI项目搭建
./references/monorepo.md
- 工作区和单仓库多项目配置

Related Skills

Summary

总结

This skill provides a streamlined path to creating production-ready TypeScript Node.js projects. By leveraging shared configuration from

@sablier/devkit

and modern tooling (Bun, Vitest, Biome, Just), new projects achieve consistency and quality from day one. Adapt the base configuration for CLI tools, libraries, or backend services as needed. Consult reference documentation for UI projects or monorepo setups when requirements extend beyond single-repository, non-UI applications.

本技能提供了一条搭建可用于生产环境的TypeScript Node.js项目的简化路径。通过使用

@sablier/devkit

的共享配置和现代化工具（Bun、Vitest、Biome、Just），新项目从第一天起就能保持一致性和高质量。可根据需要调整基础配置，以适配CLI工具、库或后端服务。当需求超出单仓库、非UI应用时，请参考相关文档以搭建UI项目或单仓库多项目架构。

template-ts-node

Original

Translation

TypeScript Node.js Project Setup

TypeScript Node.js 项目搭建

Quick Reference: Configuration Files

快速参考：配置文件

Setup Workflow

搭建流程

1. Initialize Project Structure

1. 初始化项目结构

2. Copy Configuration Files

2. 复制配置文件

3. Install Dependencies

3. 安装依赖项

4. Initialize Git Hooks

4. 初始化Git钩子

5. Create Source Structure

5. 创建源码结构

6. Verify Setup

6. 验证搭建结果

Key Configuration Choices

关键配置选择

Shared Configuration via @sablier/devkit

通过@sablier/devkit共享配置

TypeScript Configuration

TypeScript配置

Biome Configuration

Biome配置

Just Task Runner

Just任务运行器

Default recipe

默认任务

Project-specific recipes only

仅添加项目特定任务

Vitest Configuration

Vitest配置

Common Just Recipes

常用Just任务

Recipes from @sablier/devkit

来自@sablier/devkit的任务

Project-Specific Recipes

项目特定任务

Package.json Scripts

Package.json脚本

Directory Structure

目录结构

Resource Files

资源文件

Best Practices

最佳实践

Dependency Management

依赖管理

TypeScript Configuration

TypeScript配置

Testing Strategy

测试策略

Git Workflow

Git工作流

Code Organization

代码组织

Next Steps After Setup

搭建完成后的下一步

Reference Documentation

参考文档

Related Skills

相关技能

Summary

总结