my-app

（替换为你的项目介绍）

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

快速开始

git clone <your-repo-url> my-project
cd my-project
cp config.example.yaml config.yaml
bun install
bun run dev config.yaml

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

使用此模板

1. 克隆模板

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

2. 配置应用信息

编辑 src/shared/app.ts，修改应用元信息：

export const APP = {
  name: "your-app", // 机器标识（kebab-case）
  title: "Your App", // 人类可读标题
  subtitle: "你的副标题", // 副标题
  description: "应用描述", // SEO meta 描述
} as const;

同时修改 package.json 的 name 字段保持一致，version 字段管理应用版本号。

注意：localStorage key 已从 "my-app.theme.preference" 变更为 "theme.preference"。如果从旧版本升级，用户的主题偏好设置将丢失，需重新选择。

3. 准备配置文件

cp config.example.yaml config.yaml

按需编辑 config.yaml 中的监听地址、日志、存储路径等配置。

4. 清理 OpenSpec 历史

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

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

openspec/config.yaml 和 openspec/schemas/fast-drive/ 需要保留，其中包含项目开发规范配置与自定义 OpenSpec workflow schema。

5. 安装依赖

bun install

6. 开始开发

bun run dev config.yaml

项目管理

命令	说明
bun run dev <config>	启动开发模式（并行启动后端 + 前端 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 schema	生成 config.schema.json
bun run schema:check	校验 config.schema.json 是否同步
bun run check	完整质量检查：schema:check + typecheck + lint + test
bun run verify	验证构建流程：check + build
bun run clean	清理构建产物和临时文件
bun run version:patch	升迁 patch 版本（x.y.Z）
bun run version:minor	升迁 minor 版本（x.Y.0）
bun run version:major	升迁 major 版本（X.0.0）
bun run version:set	显式设置版本号

项目结构

.
├── data/                        # 运行时数据目录（日志等）
├── config.example.yaml         # 配置文件示例（server.listen 布局 + 显式变量引用）
├── config.schema.json          # 配置文件 JSON Schema（由 bun run schema 生成）
├── 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，含版本号注入）
│   ├── generate-config-schema.ts # 配置 JSON Schema 生成与同步校验脚本
│   ├── bump-version-logic.ts   # 纯版本管理逻辑（parse、validate、bump、format）
│   ├── bump-version.ts         # 版本升迁 CLI 脚本
│   └── clean.ts                # 清理脚本
├── src/
│   ├── server/                 # 后端代码
│   │   ├── bootstrap.ts        # 统一启动引导（配置加载 → 服务启动 → 优雅关闭）
│   │   ├── config.ts           # CLI 参数解析 + YAML 配置加载 facade
│   │   ├── config/             # 配置解析模块（types、issues、variables、normalizer、schema）
│   │   ├── dev.ts              # 开发模式入口
│   │   ├── main.ts             # 生产模式入口
│   │   ├── server.ts           # HTTP 服务器（Bun.serve routes 声明式路由）
│   │   ├── helpers.ts          # 共享响应工具（健康检查、JSON 响应）
│   │   ├── logger.ts           # 结构化日志（基于 pino + pino-roll）
│   │   ├── middleware.ts       # API 参数校验中间件
│   │   ├── static.ts           # 静态资源服务
│   │   └── routes/             # API 路由处理器
│   │       ├── meta.ts         # 应用元信息端点（GET /api/meta）
│   │       └── version.ts      # 版本号读取
│   ├── shared/
│   │   ├── api.ts              # 前后端共享 TypeScript 类型定义
│   │   └── app.ts              # 应用全局常量（name、title、subtitle、description）
│   └── web/                    # 前端代码
│       ├── index.html          # HTML 入口
│       ├── main.tsx            # React 入口（BrowserRouter + QueryClient + ErrorBoundary）
│       ├── app.tsx             # 根组件（Admin 布局：Header + Sidebar + Content + 版本号展示）
│       ├── routes.tsx          # 路由配置
│       ├── styles.css          # 全局样式
│       ├── css.d.ts            # CSS 模块类型声明
│       ├── pages/              # 页面组件
│       │   ├── dashboard/      # 仪表盘页
│       │   ├── users/          # 用户管理页
│       │   ├── settings/       # 系统设置页
│       │   └── 404/            # 404 页面
│       ├── components/         # UI 组件
│       │   ├── ErrorBoundary.tsx
│       │   └── Sidebar/        # 侧边栏组件
│       ├── hooks/              # React Hooks
│       ├── utils/              # 前端工具函数
│       ├── menu.tsx            # 菜单配置
│       └── routes.tsx          # 路由配置
├── tests/                      # 测试文件（镜像 src 目录结构）
├── openspec/                   # OpenSpec 规格、变更与 fast-drive workflow schema
└── docs/                       # 项目文档

配置

项目使用 YAML 配置文件，配置文件为必传参数，支持通过 JSON Schema 编辑器提示和显式变量引用。配置中的相对路径均基于配置文件所在目录解析，绝对路径保持不变。

配置文件

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

# yaml-language-server: $schema=./config.schema.json
server:
  listen:
    host: "${HOST|127.0.0.1}"
    port: ${PORT|3000}
  storage:
    dataDir: ./data
  logging:
    level: info
    console:
      level: info
    file:
      level: info
      path: "./logs/${APP.name}.log"
      rotation:
        size: 50MB
        frequency: daily
        maxFiles: 14

配置字段说明

server.listen

字段	类型	说明
host	string	监听地址，默认 127.0.0.1
port	number	监听端口，默认 3000

server.storage

字段	类型	说明
dataDir	string	数据目录，默认 ./data，相对路径基于配置文件所在目录解析

server.logging

字段	类型	说明
level	string	全局日志级别（trace / debug / info / warn / error / fatal），默认 info

server.logging.console

字段	类型	说明
level	string	控制台日志级别，未设置时继承 server.logging.level

server.logging.file

字段	类型	说明
level	string	文件日志级别，未设置时继承 server.logging.level
path	string	日志文件路径，默认 <dataDir>/logs/${APP.name}.log

server.logging.file.rotation

字段	类型	说明
size	string	按大小轮转，支持 B / KB / MB / GB 单位，默认 50MB
frequency	string	按时间轮转（hourly / daily / weekly），默认 daily
maxFiles	number	最大归档文件数，默认 14

JSON Schema

根目录 config.schema.json 为配置文件的 JSON Schema，支持 IDE 自动补全和校验。通过 # yaml-language-server: $schema=./config.schema.json 注释启用。

bun run schema        # 重新生成 config.schema.json
bun run schema:check  # 校验 schema 是否同步

变量语法

YAML 配置中支持显式变量引用：

语法	说明
${KEY}	引用变量，未定义时报错
${KEY|value}	引用变量，未定义时使用默认值
${KEY|}	引用变量，未定义时使用空字符串
$${KEY}	转义，输出 ${KEY} 原文字面量

变量解析优先级：variables 字段 → process.env → 默认值 → unresolved 报错

完整变量引用（整个值只有 ${...}）保留原始类型：${PORT|3000} 解析为 number 3000。部分拼接统一转为 string。

配置优先级

variables 字段 > 环境变量 > 默认值 > unresolved 报错

环境变量不会隐式覆盖配置，只有通过 ${KEY} 显式引用时才生效。

使用自定义配置

bun run dev custom-config.yaml

技术栈

运行时

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

后端

技术	说明
Bun.serve	HTTP 服务器，声明式路由匹配
Bun.YAML	YAML 配置文件解析
@sinclair/typebox	JSON Schema 类型构建器
Ajv	JSON Schema 运行时校验
es-toolkit	高性能工具库（推荐优先使用）
pino	结构化日志库
pino-pretty	开发环境日志美化输出
pino-roll	日志文件轮转

前端

技术	说明
React 19	UI 组件框架
React Router	SPA 路由与页面导航
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