my-app
（替换为你的项目介绍）
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. 替换占位符 my-app
在整个项目中全局搜索替换 my-app 为你的项目名称（如 your-project）。以下为所有出现位置：
| # | 文件 | 说明 |
|---|---|---|
| 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 |
测试中的品牌名断言 |
提示：可直接在编辑器中全局搜索
my-app，一次性替换。
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