TCBS Stack 用于构建可上生产环境的全栈 TypeScript 应用，技术栈由四层组成：前端使用 TanStack Start（带 SSR 的全栈 React 框架），后端使用 Convex（实时数据库与无服务器函数），认证使用 Better-Auth（通过 Convex 适配器实现灵活认证），UI 使用 Shadcn UI（可访问的组件库）。
【用途与适用场景】 适合创建带实时数据库与认证系统的 React 全栈应用，例如需要实时数据同步、用户登录与权限保护、SSR 预加载的仪表盘类产品。核心分工原则为：Convex 负责数据库与业务逻辑，TanStack Start 负责 HTTP 与渲染。
【主要能力】
- 实时数据库：Convex query 具备事务性与自动订阅能力。
- 认证体系：Better-Auth 支持邮箱密码、OAuth（如 GitHub、Google）、Magic Link、登出与会话（useSession）等方法。
- 路由保护：通过 _authed 路由在 beforeLoad 中检查认证状态并重定向。
- SSR：结合 TanStack Query 使用 ensureQueryData 与 useSuspenseQuery 进行服务端预取。
- 乐观更新：通过 useMutation(...).withOptimisticUpdate 在本地存储中先行更新查询结果。
- 类型安全数据库结构：通过 convex/schema.ts 使用 defineSchema/defineTable 定义。
【使用方式】 快速开始（推荐）： bun create @tanstack/start@latest --tailwind --add-ons shadcn cd my-app 添加 Convex（需要 v1.25.0+）： bun add convex@latest @convex-dev/react-query bunx convex dev --once 添加 Better-Auth 与 Convex： bun add better-auth @convex-dev/better-auth 手动方式： bun create @tanstack/start@latest bun add tailwindcss @tailwindcss/vite bunx shadcn@latest init
关键集成文件：src/lib/auth-client.tsx（客户端认证方法）、src/lib/auth-server.ts（SSR token 处理）、src/routes/__root.tsx（认证上下文与 Convex 客户端提供者）、src/routes/_authed.tsx（未认证用户重定向）、convex/auth.ts（Better-Auth 实例）、convex/http.ts（认证端点注册）、convex/schema.ts（类型安全 schema）。
环境变量（.env.local）： CONVEX_DEPLOYMENT=dev:your-deployment VITE_CONVEX_URL=https://your-deployment.convex.cloud VITE_CONVEX_SITE_URL=https://your-deployment.convex.site VITE_SITE_URL=http://localhost:3000 Convex 环境变量（CLI 设置）： npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32) npx convex env set SITE_URL http://localhost:3000 npx convex env set GITHUB_CLIENT_ID your-id（OAuth 可选） npx convex env set GITHUB_CLIENT_SECRET your-secret（OAuth 可选）
常用命令： bun dev（启动前端） bunx convex dev（在单独终端启动 Convex） bunx shadcn@latest add button input card form dialog（添加组件） bunx shadcn@latest add --all（添加全部组件） bun run build（构建） bunx convex deploy（部署）
【使用限制与注意事项】
- 使用 expectAuth: true 时，登出后必须刷新页面（window.location.reload()）。
- Vite 配置中需要在 ssr.noExternal 中打包 @convex-dev/better-auth。
- Convex 需 v1.25.0+；Convex query/mutation 用于数据库 CRUD 与实时数据，Convex action 用于第三方 API，认证处理器与 Webhook 使用 TanStack 服务端路由，SSR 预加载使用 TanStack loader。
- 本文档未提供收费、价格、性能指标或平台兼容范围的说明。