{{app-name}}

（替换为你的项目介绍）

Bun 全栈应用模板，基于 Bun + React + TDesign 的前后端一体化开发框架。

快速开始

git clone <your-repo-url> my-project
cd my-project
bun install
bun run dev

访问 http://127.0.0.1:5173 查看应用。

使用此模板

1. 克隆模板

git clone <template-repo-url> my-project
cd my-project
rm -rf .git && git init

2. 替换占位符 {{app-name}}

在整个项目中全局搜索替换 {{app-name}} 为你的项目名称（如 my-app）。以下为所有出现位置：

#	文件	说明
1	package.json	name 字段
2	scripts/build.ts	可执行文件路径
3	src/server/config.ts	CLI 帮助文本
4	src/server/helpers.ts	createHealthResponse() 的 service 字段
5	src/server/server.ts	服务启动日志消息
6	src/web/index.html	<title> 和 <meta name="description">
7	src/web/app.tsx	Header 中的品牌名和欢迎标题
8	src/web/hooks/use-theme-preference.ts	localStorage 键名
9	tests/web/App.test.tsx	测试中的品牌名断言

提示：可直接在编辑器中全局搜索 {{app-name}}，一次性替换。

3. 清理 OpenSpec 历史

删除模板自带的 OpenSpec 变更历史，保留框架配置：

rm -rf openspec/specs/*
rm -rf openspec/changes/*

openspec/config.yaml 需要保留，其中包含项目开发规范配置。

4. 安装依赖

bun install

5. 开始开发

bun run dev

项目管理

命令	说明
bun run dev	启动开发模式（并行启动后端 + 前端 Vite 开发服务器）
bun run dev:server	仅启动后端开发服务（--watch 热重载）
bun run dev:web	仅启动前端 Vite 开发服务器
bun run build	生产构建（Vite 打包前端 → Bun compile 生成独立可执行文件）
bun test	运行全部测试
bun run lint	ESLint 代码风格检查
bun run format	Prettier 代码格式化
bun run typecheck	TypeScript 类型检查
bun run check	完整质量检查：typecheck + lint + test
bun run verify	验证构建流程：check + build
bun run clean	清理构建产物和临时文件

项目结构

.
├── config.example.yaml         # 配置文件示例
├── bunfig.toml                 # Bun 配置（测试预加载等）
├── tsconfig.json               # TypeScript 配置
├── vite.config.ts              # Vite 构建配置（代码分包、代理）
├── eslint.config.js            # ESLint 统一配置
├── .prettierrc.json            # Prettier 格式化配置
├── commitlint.config.js        # Commitlint 提交规范配置
├── .lintstagedrc.json          # lint-staged 暂存区检查配置
├── scripts/
│   ├── dev.ts                  # 开发启动脚本（并行启动 API + Vite）
│   ├── build.ts                # 生产构建脚本（Vite → 代码生成 → Bun compile）
│   └── clean.ts                # 清理脚本
├── src/
│   ├── server/                 # 后端代码
│   │   ├── bootstrap.ts        # 统一启动引导（配置加载 → 服务启动 → 优雅关闭）
│   │   ├── config.ts           # CLI 参数解析 + YAML 配置加载
│   │   ├── dev.ts              # 开发模式入口
│   │   ├── main.ts             # 生产模式入口
│   │   ├── server.ts           # HTTP 服务器（Bun.serve routes 声明式路由）
│   │   ├── helpers.ts          # 共享响应工具（健康检查、JSON 响应）
│   │   ├── middleware.ts        # API 参数校验中间件
│   │   ├── static.ts           # 静态资源服务
│   │   └── routes/             # API 路由处理器
│   │       └── health.ts       # 健康检查端点
│   ├── shared/
│   │   └── api.ts              # 前后端共享 TypeScript 类型定义
│   └── web/                    # 前端代码
│       ├── index.html          # HTML 入口
│       ├── main.tsx            # React 入口（QueryClient + ErrorBoundary）
│       ├── app.tsx             # 根组件（Layout + 主题切换 + /health 展示）
│       ├── styles.css          # 全局样式
│       ├── css.d.ts            # CSS 模块类型声明
│       ├── components/         # UI 组件
│       ├── hooks/              # React Hooks
│       └── utils/              # 前端工具函数
├── tests/                      # 测试文件（镜像 src 目录结构）
├── openspec/                   # OpenSpec 规格与变更管理
└── docs/                       # 项目文档

配置

项目使用 YAML 配置文件，支持环境变量覆盖。

配置文件

复制 config.example.yaml 为 config.yaml（或任意名称），根据需要修改：

server:
  host: "127.0.0.1"
  port: 3000

环境变量覆盖

环境变量	对应配置字段	默认值
HOST	server.host	127.0.0.1
PORT	server.port	3000

配置优先级

环境变量 > YAML 配置文件 > 代码默认值

使用自定义配置

bun run dev custom-config.yaml

技术栈

运行时

技术	说明
Bun	JavaScript/TypeScript 运行时、包管理器、打包器
TypeScript	类型安全的 JavaScript 超集

后端

技术	说明
Bun.serve	HTTP 服务器，声明式路由匹配
Bun.YAML	YAML 配置文件解析
es-toolkit	高性能工具库（推荐优先使用）

前端

技术	说明
React 19	UI 组件框架
TDesign React	企业级 UI 组件库
@tanstack/react-query	服务端状态管理与数据获取
Recharts	图表可视化（推荐使用）
Vite	前端构建工具

工程化

技术	说明
ESLint	代码规范检查
Prettier	代码格式化
Husky	Git hooks 管理
Commitlint	Git 提交消息校验

测试

技术	说明
bun:test	Bun 内置测试框架
@testing-library/react	React 组件测试
jsdom	DOM 环境模拟

开源协议

MIT