方案简介

React Starter Kit 是一套面向 SaaS 应用的全栈 monorepo 模板。它以 React 19、tRPC 和 Cloudflare Workers 为核心，实现从数据库到 UI 的端到端类型安全，并可在数分钟内部署到边缘节点。模板内置认证（Better Auth，支持邮箱 OTP、passkey、Google OAuth、组织管理）与 Stripe 订阅计费，配合 Drizzle ORM + Neon PostgreSQL 的数据库层，开箱即可搭建带收费能力的 SaaS 产品。适合希望快速启动全栈 SaaS 项目、追求类型安全与现代 React 体验的团队和独立开发者。

亮点与能力

• Type-safe full stack – TypeScript、tRPC 与 Drizzle ORM 建立从数据库到 UI 的单一类型契约
• Edge-native – 三个 Cloudflare Workers（web、app、api）通过 service bindings 互联
• Auth + billing included – Better Auth 提供邮箱 OTP、passkey、Google OAuth、组织与 Stripe 订阅
• Modern React – React 19、TanStack Router（文件式路由）、TanStack Query、Jotai、Tailwind CSS v4、shadcn/ui
• Database ready – Drizzle ORM 配合 Neon PostgreSQL，含迁移与种子数据
• Fast DX – Bun 工具链、Vite、Vitest、ESLint、Prettier 及预配置的 VS Code 设置

组成与分工

• React 19 / TanStack Router / Jotai / Tailwind CSS v4 / shadcn/ui：主应用 SPA（apps/app）前端层
• Astro：营销站点（apps/web），边缘路由，提供静态内容并代理到 app/api
• Hono + tRPC：API 服务器（apps/api），运行于 Cloudflare Workers
• Better Auth：认证方案，含邮箱 OTP、passkey、Google OAuth、组织
• Stripe：订阅计费
• Drizzle ORM + Neon PostgreSQL：数据库层，含 schema、迁移与种子数据
• Bun / TypeScript / Vite / Vitest / ESLint / Prettier：工具链与代码质量
• Terraform：基础设施配置（Hyperdrive 连接池、R2 存储）
• React Email：邮件模板（apps/email）

实施步骤

1. 创建项目

从模板生成新仓库并克隆到本地：
bash
git clone https://github.com/your-username/your-project-name.git
cd your-project-name

2. 安装依赖

bash
bun install

3. 配置环境变量

项目遵循 Vite env 约定：.env 已提交，仅含共享默认值/占位符；.env.local 被 git 忽略，应存放真实凭据，其值覆盖 .env。
bash
cp .env .env.local # then replace placeholder values with real ones

同时检查 apps/api/wrangler.c 中的 Worker 配置与 bindings。

4. 启动开发

bash

Launch all apps in development mode (web, api, and app)

bun dev

也可单独启动：bun web:dev（营销站）、bun app:dev（主应用）、bun api:dev（API 服务器）。

5. 初始化数据库

确保 .env.local 已配置 DATABASE_URL，然后：
bash
bun db:push # Push schema directly (quick dev setup)
bun db:seed # Seed with sample data (optional)
bun db:studio # Open database GUI

生产部署

先用 Terraform 供给基础设施：
bash
bun infra:production apply

把它打印的两个 ID 粘贴到 apps/api/wrangler.c 的 hyperdrive 块。再配置生产密钥：
bash
bun wrangler secret put BETTER_AUTH_SECRET --config apps/api/wrangler.c --env=""
bun wrangler secret put RESEND_API_KEY --config apps/api/wrangler.c --env=""

使用与配置要点

开发模式下的本地地址：

| App | URL |
| --- | --- |
| React app | http://localhost:5173 |
| Marketing site | http://localhost:4321 |
| API server | http://localhost:8787 |

可选密钥：Google 登录（GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET，不配置也可用邮箱 OTP 和 passkey）；Stripe 计费（STRIPE_SECRET_KEY 等，四个全配或全不配，年付需额外配置）。要同步上游模板更新，可让编码代理运行 merge-seed skill（Claude Code 中 /merge-seed，Codex 中 $merge-seed），需保持干净的工作区。

注意事项与常见问题

• db:push 仅用于本地原型，staging 与生产环境应使用迁移：bun db:migrate:staging、bun db:migrate:production。
• 必需密钥缺失时 API 拒绝部署（BETTER_AUTH_SECRET、RESEND_API_KEY）。
• 合并上游更新前需保持干净的工作树。

优缺点

• ✓ 数据库到 UI 全程类型安全
• ✓ 认证与 Stripe 计费开箱即用
• ✕ db:push 仅限本地原型
• ✕ 部署需配置多个 Worker 密钥

出处

本方案挖掘自开源项目 kriasoft/react-starter-kit，方案内容与实施命令均来自其 README 原文。