React Starter Kit 深度解析：Edge-First 架构与 AI-Ready 的现代 React SaaS 技术栈全景

后端前端【免费下载链接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.项目地址https://gitcode.com/gh_mirrors/rea/react-starter-kit点击查看免费下载本文以 docs/index.md 为骨架系统解读 React Starter Kit 这一生产级 SaaS 起点模板的核心设计AI 优先的开发体验、面向 Cloudflare Workers 的边缘架构、React 19 现代化前端栈、开箱即用的认证与计费、多租户数据库以及基于 Bun 的极速工程化流水线。读完你将理解该仓库的每个工作区如何协作、关键配置项的底层作用以及如何从零启动并部署到生产环境。项目定位跳过数月的搭建直接交付 AI 驱动的 SaaSReact Starter Kit 的文档首页将其定位为一套production-ready monorepo认证、数据库迁移、边缘部署与业界最佳实践均已配置完毕开发者只需聚焦产品本身。仓库根目录的 README.md 进一步概括为一个用于构建 SaaS 应用的全栈 monorepo 模板技术选型覆盖 React 19、tRPC 与 Cloudflare Workers从数据库到 UI 全程类型安全可在数分钟内部署到边缘。该模板面向三类人群独立开发者Indie hackers需要快速交付 MVP初创团队需要坚实且无供应商锁定的地基团队构建多租户 SaaS 产品。首页 hero 区块提供的四个入口中「Getting Started」指向 docs/getting-started/ 文档区其余为外部资源入口。本文后续章节将围绕首页六大特性逐一展开并下沉到源码级细节。技术栈全景docs 首页并未直接罗列技术栈但结合 docs/getting-started/index.md 与 README.md 的表格全栈选型如下层级技术运行时Bun 1.3、TypeScript 6.0、ESM前端React 19、TanStack Router基于文件的路由、TanStack Query、Jotai、Tailwind CSS v4UIshadcn/uinew-york 风格营销站点Astro后端Hono、tRPC 11Zod 校验认证Better Auth——email OTP、Passkeys、Google OAuth、多租户组织计费Stripe 订阅通过 Better Auth 插件数据库Neon PostgreSQL、Drizzle ORM邮件React Email、Resend部署Cloudflare Workers、TerraformHyperdrive、R2测试Vitest 4、Happy DOM从根目录 package.json 可以看到整个仓库是一个 Bun workspaceapps/*、db、packages/*、scripts所有开发命令都以bun前缀暴露bun dev、bun test、bun lint、bun typecheck、bun run build等。特性一AI-First Development——为 AI 编码助手预配置的工程上下文首页第一个特性是AI-First Development从第一天起就与 AI 协同编码——面向 Claude Code、Cursor 与 Gemini CLI 预置了 LLM 指令、工具配置与项目上下文。这在仓库中有直接的落地证据仓库根目录与每个主要子目录apps/、db/、infra/、packages/、docs/都带有AGENTS.md / CLAUDE.md说明文件为 AI Agent 提供该目录的职责边界与操作指引根目录的skills-lock.json与 scripts/ 下的构建自动化脚本用于维护模板更新等辅助能力README.md 提到要拉取上游模板更新时可让编码 Agent 运行merge-seedskillClaude Code 中为/merge-seedCodex 中为$merge-seed它会合并上游变更、保留项目自身配置并在落地前运行项目检查——前提是工作区干净先 commit 或 stash 你的改动。从项目结构看docs/目录按getting-started、architecture、api、auth、database、billing、deployment、frontend、recipes、security、specs等领域组织见 docs/ 同级目录这种面向主题的文档划分本身就是为 AI 检索与人类速查双重设计的。特性二Edge-First Architecture——三个 Cloudflare Worker 与请求路由首页第二个特性是Edge-First Architecture为 Cloudflare Workers 构建具备优化的性能、全球分发与即时部署。这是整个架构的灵魂详见 docs/architecture/index.md。三个 Worker 的职责划分Worker工作区职责是否启用nodejs_compatwebapps/web营销站点 边缘路由器接收全部流量转发到 app/api否appapps/appSPA 静态资源React、TanStack Router否apiapps/apiHono 服务器——tRPC、Better Auth、Webhook是核心不变量只有 web worker 挂接公共域名app 与 api 通过 service bindings 被内部调用不存在跨 Worker 的公共 URL 往返。边缘路由的真实实现以 apps/web/worker.ts 为证web worker 的路由决策非常明确// apps/web/worker.ts核心片段 const APP_PATHS [_app, login, members, settings, signup] as const; // API 代理 app.all(/api/*, (c) c.env.API_SERVICE.fetch(c.req.raw)); // 精确路径 其斜杠子路径避免裸前缀误伤 /members-only 这类共享前缀 for (const path of APP_PATHS) { app.all(/${path}, (c) c.env.APP_SERVICE.fetch(c.req.raw)); app.all(/${path}/*, (c) c.env.APP_SERVICE.fetch(c.req.raw)); } // 首页依据 auth-hint cookie 决定展示 SPA 还是营销页 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); // 设置 Cache-Control: private, no-store 与 Vary: Cookie防止响应被缓存 // ... });关键点_app是 Vite 构建产物路径/通过auth hint cookie分流——__Host-auth1HTTPS或auth1本地 HTTP 开发环境存在则进入 SPA否则返回营销页。该 cookie 只是路由提示而非安全边界web worker 从不校验会话误判最多导致一次额外跳转到/login真正的会话校验由 app worker 完成。完整决策记录见 docs/adr/001-auth-hint-cookie.md。apps/app/lib/edge-routing.test.ts测试会反向校验APP_PATHS与应用自有顶层路由apps/app/routes/是否保持同步防止路由遗漏导致直连请求落入营销站点。Worker 配置与不变量apps/app/wrangler.jsonc 声明assets.not_found_handling: single-page-application任何未命中文件的路径都返回index.html从而支撑 TanStack Router 的客户端路由app worker 没有自定义脚本。apps/api/wrangler.jsonc 启用nodejs_compat其余两个 Worker 没有并声明两个 Hyperdrive 绑定HYPERDRIVE_CACHED/HYPERDRIVE_UNCACHED、必需的 secret 契约[BETTER_AUTH_SECRET, RESEND_API_KEY]。Service bindings 不可继承Wrangler 要求每个环境块重复声明绑定遗漏会导致 staging worker 错误绑定到生产服务。命名约定为project-worker-env例如example-api-staging。API Worker 的中间件链apps/api/lib/app.ts 展示了 Hono 应用的组装secureHeaders()、requestId()、logger()中间件随后初始化共享上下文db、dbCached、auth再挂载 tRPC 与认证路由。主要端点路径处理器/api/auth/*Better Auth登录、注册、会话、OAuth 回调/api/trpc/*tRPC procedures启用 batching/apiAPI 信息名称、版本、端点列表/health健康检查环境矩阵环境运行时域名数据库命令DevelopmentVite/Astro/Bunlocalhost:5173开发分支bun devStaging*-stagingstaging.example.com主分支wrangler deploy --env stagingProduction*无后缀example.com主分支wrangler deploy --env本地开发通过 Wrangler 的getPlatformProxy()模拟 Hyperdrive 绑定各自解析到.env中的CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE_*变量直连 Postgres因此本地不启用连接池与查询缓存。特性三Modern React Stack——React 19 与全链路类型安全首页第三个特性是Modern React StackReact 19 Vite 与 Astro、TanStack Router、Jotai 状态管理、shadcn/ui 组件Tailwind CSS v4。仓库落地情况apps/app/ 是 Vite 构建的 React 19 SPA路由基于文件系统apps/app/routes/支持路由组例如(app)下的仪表盘、成员、设置页面(auth)下的登录、注册页面见 apps/app/routes/服务端状态由 TanStack Query 管理客户端状态由 Jotai 管理apps/app/lib/UI 组件来自 packages/ui/即 shadcn/uinew-york 风格组件库支持用bun ui:add name增补、bun ui:list查看、bun ui:update更新组件apps/web/ 是 Astro 构建的营销站点为未登录访客提供落地页全链路类型安全前端 tRPC 客户端与后端路由共享同一类型契约修改 tRPC 路由后类型自动更新无需手工同步docs/getting-started/quick-start.md。tRPC 的底层实现见 apps/api/lib/trpc.ts通过initTRPC.contextTRPCContext()创建实例errorFormatter将 Zod 校验错误扁平化输出到响应的data.zodError字段protectedProcedure是包了一层鉴权中间件的 procedure builder未登录时抛出UNAUTHORIZED的TRPCError。每个请求的上下文apps/api/lib/context.ts携带db不缓存、dbCached可缓存两个数据库客户端以及session/user未登录为null。特性四Auth Billing Included——认证与计费开箱即用首页第四个特性是Auth Billing IncludedBetter Auth 提供社交登录、Passkeys、组织以及通过托管 checkout 实现的 Stripe 订阅。详见 docs/auth/index.md。开箱即用的认证方式方式说明Email OTP免密码的 6 位邮箱验证码Email Password服务端已启用含重置邮件starter UI 未内置密码表单Google OAuth社交登录重定向流程可选PasskeysWebAuthn 生物识别 / 安全密钥Anonymous访客会话能力starter UI 未内置会话控制所有方式产出同一种会话格式用户可将多种方式绑定到同一账号。Better Auth 插件矩阵服务端与客户端须成对启用插件服务端客户端用途emailOTPemailOTP()emailOTPClient()免密码 OTP 登录organizationorganization()organizationClient()多租户组织与角色passkeypasskey()passkeyClient()WebAuthn 认证anonymousanonymous()anonymousClient()访客会话stripestripe()stripeClient()订阅计费Stripe 插件是条件加载的只有四个必需的STRIPE_*变量全部设置时才激活。全部未设置时应用照常工作受保护的billing.subscription查询会报告集成未启用Stripe 变更端点返回 404只设置部分变量时createAuth会直接抛错——半配置的部署会快速失败而不是表现为功能缺失。服务端配置要点apps/api/lib/auth.ts 中createAuth()的配置文档示例节选展示了关键参数baseURL与trustedOrigins绑定到env.APP_ORIGINemailAndPassword与emailVerification通过 React Email 模板apps/email/emails/发送密码重置与验证邮件socialProviders使用googleProvider(env)——两个 Google 凭据都设置才启用只设置一个会抛错插件配置示例organization({ allowUserToCreateOrganization: true, organizationLimit: 5, creatorRole: owner })、passkey({ rpID, rpName: env.APP_NAME, origin: env.APP_ORIGIN })、emailOTP({ otpLength: 6, expiresIn: 300, allowedAttempts: 3 })通过advanced.database.generateId使用应用层生成的前缀 CUID2 ID如usr_cm...、ses_cm...、org_cm...方便识别记录类型account模型被重命名为identity用于承载所有认证身份OAuth 与密码。认证相关环境变量变量必填说明BETTER_AUTH_SECRET是会话与令牌签名密钥GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET否Google OAuth 凭据须成对设置RESEND_API_KEY是发送 OTP 邮件的 API KeyRESEND_EMAIL_FROM是认证邮件的发件地址APP_NAME是展示名称用于邮件与 Passkey 提示APP_ORIGIN是完整来源 URL如https://example.com这些契约在 apps/api/lib/env.ts 中以 Zod schema 定义并推导出Env类型BETTER_AUTH_SECRET至少 32 字符、STRIPE_SECRET_KEY以sk_开头、STRIPE_WEBHOOK_SECRET以whsec_开头、STRIPE_*_PRICE_ID以price_开头可选集成全部使用.optional()——这正是可选功能在特性边界处门控的实现基础。认证数据落库在 9 张表中db/schema/user、session含activeOrganizationId、identity、verification、organization、member含角色、invitation、passkey、subscription。特性五Multi-Tenant Database——多租户数据库与迁移体系首页第五个特性是Multi-Tenant DatabaseNeon PostgreSQL Drizzle ORM预置多租户 schema组织、迁移、类型安全查询。详见 docs/database/index.md。工作区结构db/ ├── schema/ # 表定义与关系按领域分文件schema/index.ts 统一再导出 ├── migrations/ # 自动生成的 SQL 迁移 ├── seeds/ # 种子数据脚本 ├── scripts/ # 工具seed 运行器、导出 ├── drizzle.config.ts # Drizzle Kit 配置 └── index.ts # 再导出 schema DatabaseSchema 类型repo/db包提供两个入口import * as schema from repo/db完整 schema 类型与import { user, session } from repo/db/schema单表导入。双 Hyperdrive 绑定绑定缓存用途HYPERDRIVE_CACHED默认 60 秒 15 秒 stale可容忍过期数据的读密集查询HYPERDRIVE_UNCACHED无写入与任何需要新鲜数据的场景两个绑定都暴露在 tRPC 上下文中ctx.db与ctx.dbCached。Better Auth 一律使用db不缓存——过期的会话或角色行会幸存于登出或权限变更之后。连接创建见 apps/api/lib/db.ts 的简化实现postgres(hyperdrive.connectionString, { max: 1 })限制每请求两个客户端共享连接预算并配合casing: snake_case的 Drizzle 配置。数据库命令从仓库根目录执行部分命令带:staging/:production后缀命令说明bun db:generate由 schema 变更生成迁移 SQLbun db:migrate应用待执行迁移bun db:push直接推送 schema跳过迁移文件仅本地原型bun db:studio打开 Drizzle Studio 图形界面bun db:seed运行种子脚本bun db:check检查迁移历史冲突bun db:export用 pg_dump 导出到db/backups/bun db:typecheck对db/工作区做类型检查环境定向的关键设计数据库脚本通过ENVIRONMENT变量回退NODE_ENV选择环境。开发环境按dev.local → .env.local → .env级联首个命中生效staging 与 production 不级联——bun db:migrate:production只读.env.production.local文件缺失则命令直接失败杜绝环境命名命令误落到其他环境数据库。db:seed只有:staging变体种子会创建测试账号不该进生产db:generate与db:push没有远程变体前者不连库后者仅限原型。DATABASE_URL必须是合法的postgres://或postgresql://连接串。特性六Ship Faster——Bun 驱动的极速交付与一站式工具链首页第六个特性是Ship FasterBun 运行时带来即时构建、热重载、统一工具链与完善的测试配置。在根目录 package.json 中可以看到一整套bun前缀脚本bun dev并发启动 web、api、app 三个服务bun --filter按工作区筛选bun testVitest 4 Happy DOM、bun lintESLint 带缓存、bun typechecktsc --build、bun run build按依赖顺序构建 email → api → web/app 等可部署工作区邮件模板预览bun email:devapps/email/UI 组件管理bun ui:add/bun ui:list/bun ui:update文档bun docs:dev/bun docs:buildVitePress即本仓库 docs/ 的生成方式基础设施bun infra:staging/bun infra:production包装 Terraform 命令。构建顺序的依赖关系API 服务器 import 编译后的 email 包因此 email 工作区必须先构建web 与 app 构建相互独立bun run build让 Bun 自动排序依赖并尽早执行独立任务。快速开始从零到本地三服务跑起来综合 docs/getting-started/quick-start.md 与 README.md快速启动路径如下。前置条件Bun 1.3.0本项目完全运行在 Bun 上Node.js 非必需Cloudflare 账号免费档即可用于部署。方式 A——GitHub 模板使用仓库的 Use this template 创建新仓库后git clone并bun install得到无模板提交历史的全新仓库。方式 B——Git clone便于后续同步上游git clone -o seed -b main --single-branch \ https://github.com/kriasoft/react-starter-kit.git my-app cd my-app bun install git remote add origin https://github.com/YOUR_USERNAME/YOUR_PROJECT.git git push -u origin main以seed命名远端后后续可用merge-seedskill 拉取模板更新要求工作区干净。配置环境变量项目遵循 Vite 的 env 约定——.env提交到 git仅含共享默认值与占位符.env.local被 git 忽略存放真实凭据并覆盖.envcp .env .env.local # 然后把占位符替换为真实值Worker 级配置见各 apps/*/wrangler.jsonc含compatibility_date、hyperdrive绑定、secrets.required契约等。启动开发服务器bun dev服务URL说明Apphttp://localhost:5173React SPA热重载APIhttp://localhost:8787Hono tRPC 服务器Webhttp://localhost:4321Astro 营销站点Emailhttp://localhost:3001bun email:dev模板预览也可单独启动bun app:dev、bun api:dev、bun web:dev、bun email:dev。初始化数据库确保.env.local中配置DATABASE_URL后bun db:push # 直接推送 schema本地快速开发 bun db:seed # 可选写入示例数据 bun db:studio # 打开数据库 GUIdb:push仅限本地原型staging/production 应改用bun db:migrate:staging/bun db:migrate:production。开始改造项目更新 apps/app/index.html 的品牌信息、编辑首页 apps/app/routes/(app)/index.tsx/index.tsx)、在 apps/api/routers/ 新增 tRPC procedures、在 db/schema/ 定义数据模型。修改 tRPC 路由后类型自动更新编辑 schema 后依次运行bun db:generate与bun db:push。生产部署要点部署流程在 README.md 中有精炼版本完整步骤见文档的 Deployment 分区。三个关键步骤1. 用 Terraform 提供基础设施Hyperdrive 连接池API worker 经由它连库bun infra:production apply把输出的两个 ID 粘贴进 apps/api/wrangler.jsonc 的hyperdrive块。2. 配置生产 secrets全部属于 API worker--config apps/api/wrangler.jsonc用于选定 worker--env显式选择顶层 production 环境# 必需——缺少它们 API 拒绝部署 bun wrangler secret put BETTER_AUTH_SECRET --config apps/api/wrangler.jsonc --env bun wrangler secret put RESEND_API_KEY --config apps/api/wrangler.jsonc --env # Google 登录可选 bun wrangler secret put GOOGLE_CLIENT_ID --config apps/api/wrangler.jsonc --env bun wrangler secret put GOOGLE_CLIENT_SECRET --config apps/api/wrangler.jsonc --env # Stripe 计费可选——要么全设四个要么全不设 bun wrangler secret put STRIPE_SECRET_KEY --config apps/api/wrangler.jsonc --env bun wrangler secret put STRIPE_WEBHOOK_SECRET --config apps/api/wrangler.jsonc --env bun wrangler secret put STRIPE_STARTER_PRICE_ID --config apps/api/wrangler.jsonc --env bun wrangler secret put STRIPE_PRO_PRICE_ID --config apps/api/wrangler.jsonc --env bun wrangler secret put STRIPE_PRO_ANNUAL_PRICE_ID --config apps/api/wrangler.jsonc --env # 可选非敏感变量如RESEND_EMAIL_FROM直接写在wrangler.jsonc。务必把RESEND_EMAIL_FROM设为你在 Resend 已验证域名下的地址——默认的onboardingresend.dev只能投递到你的收件箱而登录依赖邮箱 OTP留着默认值会导致除你之外无人能登录。3. 迁移生产数据库并按序部署bun db:migrate:production # 只读 .env.production.local bun run build # 构建全部可部署工作区 bun api:deploy --env # 先部署 service-binding 目标 bun app:deploy --env bun web:deploy --env # web 路由器最后部署进一步阅读文档导航与源码入口本文基于 docs/index.md 展开。若想深入各子系统文档区由 VitePress 构建根目录bun docs:dev可本地预览按主题组织Quick Start 与 Project Structure 介绍上手与目录Architecture 详解 Worker 模型与请求流Auth、Database、Billing、Deployment 分别覆盖各子系统Recipes 提供常见任务的逐步指南ADR 记录关键架构决策。值得对照的源码入口边缘路由 apps/web/worker.ts、API 组装 apps/api/lib/app.ts、环境契约 apps/api/lib/env.ts、tRPC 初始化 apps/api/lib/trpc.ts、请求上下文 apps/api/lib/context.ts、数据库 schema db/schema/index.ts 与根脚本清单 package.json。结合这些文件阅读可以验证本文所述每一项能力背后的真实实现。赞分享后端前端【免费下载链接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.项目地址https://gitcode.com/gh_mirrors/rea/react-starter-kit点击查看免费下载相关推荐React Starter Kit 全栈模板深度解析Bun React 19 tRPC Cloudflare Workers 的 SaaS 起手式React Starter Kit 全栈模板深度解析Bun React 19 tRPC Cloudflare Workers 的 SaaS 起手式后端前端深度解析Next SaaS Stripe Starter 核心架构与技术栈深度解析Next SaaS Stripe Starter 核心架构与技术栈 Next SaaS Stripe Starter 是一个功能强大的开源 SaaSChat Nio架构解析GoReact全栈技术栈深度剖析Chat Nio架构解析GoReact全栈技术栈深度剖析 ? 项目概述与技术栈全景 Chat Nio是一个革命性的AI聚合聊天平台采用 Go Reac后端前端人工智能大模型AI 应用LLM 网关API网关上一篇pig-mesh/pig的公共参数配置打造企业级微服务配置管理新范式下一篇Dart Simple Live活动系统专题活动与运营功能深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考