React Starter Kit 项目结构完全指南:Bun Monorepo 四应用架构、共享包与部署布局解析

原创2026-09-19 16:40:531,617 阅读
文章标签:后端前端

React Starter Kit 项目结构完全指南:Bun Monorepo 四应用架构、共享包与部署布局解析

本指南以 docs/getting-started/project-structure.md 为主线,系统拆解 React Starter Kit 的 Monorepo 目录布局:四个应用(apps/)、四个共享包(packages/)、数据库工作区(db/)、基础设施(infra/)与文档(docs/)各自的职责边界。读完你将掌握每个目录的定位、三个 Cloudflare Worker 之间的 service binding 调用关系、关键配置文件的用途,以及各工作区对应的常用命令,能够快速在新代码库中定位任意功能的实现位置。

总体布局:一个 Bun Workspace Monorepo

React Starter Kit 是一个基于 Bun 的 Monorepo(Bun workspace)。根目录的 package.json 以 "workspaces" 字段声明了所有纳入包管理的工作区:

"workspaces": [
  "apps/*",
  "db",
  "packages/*",
  "scripts"
]

项目顶层目录结构如下:

my-app/
├── apps/
│   ├── web/           # Edge router + Astro marketing site
│   ├── app/           # React 19 SPA (TanStack Router)
│   ├── api/           # Hono + tRPC API server
│   └── email/         # React Email templates
├── packages/
│   ├── ui/            # shadcn/ui component library
│   ├── core/          # Shared utilities
│   ├── ws-protocol/   # WebSocket protocol template
│   └── typescript-config/  # Shared tsconfig presets
├── db/                # Drizzle ORM schemas and migrations
├── infra/             # Terraform (Hyperdrive, R2)
├── docs/              # Documentation (VitePress)
├── scripts/           # Build and utility scripts
└── package.json       # Monorepo root

从结构上看,这是一个"应用(apps)+ 共享包(packages)+ 数据库工作区(db)+ 基础设施(infra)"四层分治的布局:应用层彼此独立、可单独部署;共享包提供跨应用复用的组件、工具与配置;db 作为独立工作区承载数据模型与迁移;infra 管理 Worker 之外的云资源。根 package.json 还暴露了大量便捷脚本(bun app:dev、bun api:dev、bun db:migrate、bun ui:add 等),把对各个工作区的操作收敛到仓库根目录统一执行。

四个应用:职责划分与边界

apps/web —— 边缘路由器 + 营销站点

apps/web 是一个 Cloudflare Worker,作为对外统一的公共入口。它承担三层职责:

  1. 路由 /api/* 到 API Worker;
  2. 路由应用页面路径(/login、/settings、/members、/signup 等)到 App Worker;
  3. 为未登录访客提供 Astro 构建的营销站点(首页、特性页、定价页、关于页)。

其内部路径分发的核心逻辑在 apps/web/worker.ts:通过 APP_SERVICE 与 API_SERVICE 两个 service binding(服务绑定)把请求转发给另外两个 Worker。APP_PATHS 常量集中登记了需要转发给 App Worker 的顶层路径:

const APP_PATHS = [
  "_app", // Vite build output (JS, CSS, assets)
  "login",
  "members",
  "settings",
  "signup",
] as const;

代码注释强调:这个清单必须与 apps/app/routes/ 下的应用自有顶层路由保持同步,否则直接访问某条应用路由时会落到营销站点的 404。apps/app/lib/edge-routing.test.ts 正是用来双向校验这份清单与路由文件一致性的测试。

web 与 app 之间的"边界仲裁"依赖一个认证提示 Cookie(auth hint cookie):web 不持有任何认证逻辑,只通过检查 __Host-auth(HTTPS 下)或 auth(HTTP 本地开发下)这两个 Cookie 的值是否为 1,决定 / 展示 App 还是落地页:

app.on(["GET", "HEAD"], "/", async (c) => {
  const hasAuthHint =
    getCookie(c, "__Host-auth") === "1" || getCookie(c, "auth") === "1";
  const upstream = await (hasAuthHint ? c.env.APP_SERVICE : c.env.ASSETS).fetch(
    c.req.raw,
  );
  // ...
});

这一设计来自 ADR-001:Auth Hint Cookie 用于边缘路由——它只是路由提示而非安全边界,Cookie 误判最多导致一次多余的 /login 重定向,而真正的会话校验始终在 App Worker 内部完成。/ 响应的 Cache-Control: private, no-store 与 Vary: Cookie 头则防止边缘层按登录态缓存错误版本。

营销站点本身由 Astro 构建(apps/web/astro.config.mjs,output: "static"),页面位于 apps/web/pages/(index.astro、features.astro、pricing.astro、about.astro),布局在 apps/web/layouts/BaseLayout.astro。对应的 Worker 配置见 apps/web/wrangler.jsonc,其中 "assets" 块通过 run_worker_first: ["/"] 强制根路径先经过 Worker 逻辑再回落到静态资源,从而支持登录态感知的路由。

apps/app —— React 19 前端 SPA

apps/app 是面向已登录用户的应用主体,一个用 Vite 构建的 React 19 单页应用:

  • 路由:TanStack Router,基于文件的路由,路由文件位于 apps/app/routes/(含 (app) 布局组下的 index.tsx、members.tsx、settings.tsx,以及 (auth) 组下的 login.tsx、signup.tsx,根路由为 __root.tsx);
  • 服务端状态:TanStack Query(apps/app/lib/queries/ 下按领域拆分查询模块,如 billing.ts、session.ts、organization.ts);
  • 客户端状态:Jotai(apps/app/lib/store.ts);
  • UI 组件:shadcn/ui(来自 packages/ui);
  • 样式:Tailwind CSS v4(apps/app/tailwind.config.css)。

部署形态同样是 Cloudflare Worker + 静态资源(wrangler.jsonc 中 assets.not_found_handling: "single-page-application",保证 SPA 路由在边缘层也能正确回退到 index.html)。组件层集中在 apps/app/components/(auth/、layout/、user-menu.tsx 等),类型安全的 tRPC 客户端位于 apps/app/lib/trpc.ts。

apps/api —— Hono + tRPC API 服务器

apps/api 是唯一的"重" Worker,运行 Hono 负责 HTTP 路由、tRPC 负责类型安全的 RPC 层。它的核心职责:

  • 认证:Better Auth(apps/api/lib/auth.ts),支持邮箱 OTP、passkeys、Google OAuth 与组织(organization)能力;
  • 数据库访问:Drizzle ORM,通过 Cloudflare Hyperdrive 连接池访问 Neon PostgreSQL(绑定 HYPERDRIVE_CACHED / HYPERDRIVE_UNCACHED,见 apps/api/wrangler.jsonc);
  • 计费:Stripe 订阅与 Webhook(apps/api/routers/billing.ts);
  • 邮件发送:通过 Resend 发送 React Email 模板(apps/api/lib/email.ts)。

tRPC 路由器集中在 apps/api/routers/(billing.ts、config.ts 等),中间件与上下文在 apps/api/lib/middleware.ts、apps/api/lib/context.ts。重要区别:apps/api 的 wrangler.jsonc 开启了 compatibility_flags: ["nodejs_compat"],而另外两个 Worker 没有——因为它需要 Node.js 兼容运行时来支撑 Better Auth、Stripe、Resend 等依赖。

本地开发时,apps/api/dev.ts 通过 Wrangler 的 getPlatformProxy 选择 dev 环境,用占位 Hyperdrive ID 配合 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE_{CACHED,UNCACHED} 指向任意本地 Postgres 实例。

apps/email —— React Email 模板

apps/email 存放使用 React Email 编写的邮件模板,覆盖 OTP 验证码、邀请、密码重置、验证邮件等事务性邮件场景(apps/email/emails/ 与 apps/email/templates/,共用 apps/email/components/BaseTemplate.tsx 基础布局)。

  • 模板在 API 开发服务器启动之前构建完成(apps/api/package.json 中的 "predev": "bun --filter @repo/email build"),以保证运行时可用;
  • 预览使用 bun email:dev,启动在 http://localhost:3001;
  • 构建产物通过 exports 暴露为 @repo/email(含 ./templates/* 子路径),供 apps/api 在运行时渲染并交给 Resend 发送。

共享包:跨应用复用层

包 说明 关键内容
packages/ui shadcn/ui 组件库(new-york 风格),基于 Tailwind CSS v4。新增组件用 bun ui:add <name> components/(button、dialog、select、checkbox 等),packages/ui/index.ts,scripts/ 下的 add/update/list/essentials 工具
packages/core 跨应用复用的共享工具函数与常量 packages/core/index.ts
packages/ws-protocol 实时功能用的 WebSocket 消息协议模板 packages/ws-protocol/messages.ts、router.ts、example.ts
packages/typescript-config 共享 tsconfig.json 预设,统一各工作区编译器设置 base.jsonc、node.jsonc、cloudflare.jsonc、react.jsonc

其中 packages/typescript-config 体现了 Monorepo 的"配置即包"思路:不同运行时(Node、Cloudflare Worker、React)各有一份预设,各应用与工作区在各自 tsconfig.json 中通过 extends 引用,保证编译器选项全仓库一致。

数据库工作区:db/

db/ 是独立的 Drizzle ORM 工作区,包含:

  • 表定义:db/schema/,按领域拆分(user.ts、organization.ts、invitation.ts、passkey.ts、subscription.ts、id.ts),统一出口在 db/schema/index.ts;
  • 迁移文件:db/migrations/(当前基线 0000_init.sql 与 meta/ 快照);
  • 种子脚本:db/seeds/users.ts 与 scripts/seed.ts;
  • 导出工具:scripts/export.ts。

它面向 Neon PostgreSQL,并通过 Cloudflare Hyperdrive 做连接池。迁移配置在 db/drizzle.config.ts:dialect: "postgresql"、casing: "snake_case"、out: "./migrations"、schema: "./schema"。值得注意的安全设计:staging/production 环境fail closed——必须存在对应的 .env.staging.local / .env.production.local 且其中定义 DATABASE_URL,否则拒绝执行迁移,防止误把环境命名迁移打到错误的数据库;开发环境则按 .env.dev.local → .env.local → .env 的优先级级联读取(首个命中生效,与 Vite 约定一致)。

常用数据库命令(仓库根目录执行):

bun db:generate             # 根据 schema 生成迁移
bun db:migrate              # 应用迁移(开发环境)
bun db:migrate:staging      # 应用迁移到 staging(ENVIRONMENT=staging)
bun db:migrate:production   # 应用迁移到 production
bun db:push                 # 直接推送 schema(开发)
bun db:studio               # 打开 Drizzle Studio GUI
bun db:seed                 # 执行种子脚本
bun db:export               # 导出数据

基础设施:infra/

infra/ 存放 Terraform 配置,但它只管理 Hyperdrive 与 R2 这类云资源,不管理三个 Worker 本身(Worker 由各自的 wrangler.jsonc 与 bun deploy 脚本负责)。

infra/
├── envs/
│   ├── production/main.tf
│   └── staging/main.tf
└── modules/
    └── cloudflare/         # main.tf / outputs.tf / variables.tf

从目录结构看,它遵循"环境(envs)+ 模块(modules)"的标准 Terraform 组织:modules/cloudflare 封装 Cloudflare 资源的可复用模块,envs/ 下的每个环境通过 terraform -chdir=infra/envs/<env> 独立执行。根 package.json 提供了 bun infra:staging、bun infra:production 快捷入口以及 bun infra:check(先 terraform fmt -check 再对每个环境 init -backend=false && validate)。

关键配置文件速查

文件 用途
infra/ Hyperdrive 与 R2 的 Terraform 配置(不含 Worker 本身)
apps/*/wrangler.jsonc 各应用的 Cloudflare Worker 配置(worker 名、assets、service bindings、环境变量、secrets、routes)
db/drizzle.config.ts Drizzle ORM 迁移配置(schema 路径、迁移输出、PostgreSQL 方言、环境感知的 env 加载)
.env 共享环境默认值(提交到 Git)
.env.local 本地密钥与覆盖(被 Git 忽略)
tsconfig.json 根 TypeScript 工程引用(tsc --build 依赖 packages/typescript-config 预设)
package.json Monorepo 根:workspaces、脚本、开发依赖

环境变量采用"两层文件"模式:.env 提供所有人共享的默认值(提交入库),.env.local 存放本地密钥与覆盖(git-ignored)。所有 wrangler deploy 脚本都通过 --env-file ../../.env --env-file ../../.env.local 把这两份文件带入 Wrangler(见 apps/app/package.json、apps/api/package.json)。

把结构映射到开发命令

理解了目录布局后,根 package.json 中的脚本就变得一目了然——每个脚本都直接对应一个工作区:

bun dev                  # 并行启动 web、api、app 三个服务
bun app:dev              # 仅启动 React SPA(http://localhost:5173)
bun api:dev              # 仅启动 API(http://localhost:8787),predev 会先构建邮件模板
bun web:dev              # 仅启动 Astro 营销站(http://localhost:4321)
bun email:dev            # 邮件模板预览(http://localhost:3001)
bun run build            # 按 email → web → api → app 顺序构建全部可部署工作区
bun test                 # 全仓库 Vitest 测试
bun typecheck            # tsc --build 类型检查
bun ui:add <name>        # 向 packages/ui 添加 shadcn/ui 组件

从源码结构可以推断出一个清晰的依赖方向:web 是唯一对外暴露域名的入口,通过 service binding 代理到 app 与 api;app 通过 tRPC 客户端消费 api;api 依赖 @repo/db(数据模型)、@repo/email(邮件模板)与 @repo/core(共享工具);ui 与 typescript-config 则被前端相关工作区共享。这套"边缘路由 + SPA + API"的三 Worker 架构,配合 db/infra 的独立治理,正是 React Starter Kit 在生产环境部署形态上的核心骨架。

继续深入

登录后查看全文
react-starter-kit