# TCBS 堆栈使用 TanStack Start + Convex + Better-Auth + Shadcn UI 构建生产就绪的全栈 TypeScript 应用程序。 ## 堆栈概述层 |技术 |目的 ---|---|--- **前端** |开始 | TanStack带有 SSR 的全栈 React 框架 **后端** |凸|实时数据库和无服务器功能 **授权** |更好的验证 |使用凸适配器进行灵活的身份验证 **用户界面** | Shadcn UI |可访问的组件库 ## 快速入门 # 使用 Shadcn 创建新的 TanStack Start 项目（推荐）面包创建@tanstack/start@latest --tailwind --add-ons shadcn cd 我的应用程序 # 添加凸（需要 v1.25.0+）包子添加凸@最新@凸-dev/react-query Bunx凸开发--once # 使用凸添加更好的验证包添加更好的身份验证@convex-dev/better-auth **替代手动设置：** 面包创建@tanstack/start@latest 发髻添加 tailwindcss @tailwindcss/vite Bunx shadcn@最新初始化 ## 项目结构项目/ ├── src/ │ ├── 库/ │ │ ├── auth-client.tsx # 客户端认证设置 │ │ ├── auth-server.ts # 服务器认证处理程序 │ │ └── utils.ts # cn() 帮助器 │ ├── 路线/ │ │ ├── __root.tsx # 根布局 + 提供者 │ │ ├── _authed.tsx # 受保护的路由守卫 │ │ ├── _已验证/ │ │ │ └──index.tsx # 仪表板 │ │ ├── 登录.tsx │ │ └── 注册.tsx │ ├── 组件/ │ │ └── ui/ # Shadcn 组件 │ └── 路由器.tsx ├── 凸/ │ ├── auth.ts # Better-Auth 实例 │ ├── auth.config.ts # 身份验证提供者配置 │ ├── http.ts # HTTP 路由 │ ├── schema.ts # 数据库模式 │ └──凸面.config.ts # 应用程序配置 ├── Components.json # Shadcn 配置 └── vite.config.ts ## 核心设置文件 ### 1\.凸配置 **凸/凸.config.ts** 从“凸/服务器”导入{defineApp}；从“@convex-dev/better-auth/convex.config”导入betterAuth； const app = DefineApp(); 应用程序.use(betterAuth); 导出默认应用程序； **凸/auth.config.ts** 从“@convex-dev/better-auth/auth-config”导入{ getAuthConfigProvider }；从“@auth/core”导入{AuthConfig}；导出默认值{ 提供者：[getAuthConfigProvider()]， } 满足AuthConfig； **凸/auth.ts** 从“@convex-dev/better-auth”导入{createClient，GenericCtx}；从“@convex-dev/better-auth/plugins”导入{凸}；从“better-auth”导入{betterAuth}；从“./_ generated/dataModel”导入{DataModel}；从“./_ generated/api”导入{组件，内部}；从“./auth.config”导入authConfig； const siteUrl = process.env.SITE_URL!; 导出 const authComponent = createClient(components.betterAuth, { authFunctions：内部.auth，触发器：{ 用户：{ onCreate: async (ctx, authUser) => { // 同步到您的用户表 const userId = wait ctx.db.insert("users", { email: authUser.email }); 等待 authComponent.setUserId(ctx, authUser._id, userId); }, }, }, }); 导出 const createAuth = (ctx: GenericCtx) => { 返回更好的Auth({ 基本网址：站点网址，数据库：authComponent.adapter(ctx), emailAndPassword: { 启用: true }, 插件：[凸（{ authConfig }）]， }); }; // 用于查询/突变的身份验证助手导出 const { getUser, safeGetUser } = authComponent.authHelpers(createAuth); **凸/http.ts** 从“凸/服务器”导入{httpRouter}；从“./auth”导入{authComponent，createAuth}； const http = httpRouter(); authComponent.registerRoutes(http, createAuth); 导出默认http； **凸/schema.ts** 从“凸/服务器”导入{defineSchema，defineTable}；从“凸/值”导入 { v }；导出默认的defineSchema({ 用户：定义表（{ 电子邮件：v.string(), authId: v.可选(v.string()), }).index("电子邮件", ["电子邮件"]), }); ### 2\.客户端验证设置 **src/lib/auth-client.tsx** 从“better-auth/react”导入{createAuthClient}；从“@convex-dev/better-auth/client/plugins”导入{凸客户端}；导出 const authClient = createAuthClient({ 插件：[凸客户端()]， }); 导出 const { 登录、注册、退出、useSession } = authClient; ### 3\.服务器验证设置 **src/lib/auth-server.ts** 从“@convex-dev/better-auth/react-start”导入{convexBetterAuthReactStart}；导出常量{ 处理程序, 获取令牌，获取验证查询， fetchAuthMutation，获取验证操作， } = 凸BetterAuthReactStart({ 凸Url：process.env.VITE_CONVEX_URL！，凸面站点Url：process.env.VITE_CONVEX_SITE_URL！， }); ### 3b。挂载身份验证路由处理程序 **src/routes/api/auth/$.ts** 从“~/lib/auth-server”导入{处理程序}；导出 const { GET, POST } = 处理程序； ### 4\.与提供商的根路由 **src/routes/__root.tsx** 从“@tanstack/react-router”导入{createRootRouteWithContext，Outlet}；从“@tanstack/react-start”导入{createServerFn}；从“@convex-dev/better-auth/react”导入{ConvexBetterAuthProvider}；从“@tanstack/react-query”导入{QueryClient}；从“@convex-dev/react-query”导入{ConvexQueryClient}；从“~/lib/auth-server”导入{ getToken }；从“~/lib/auth-client”导入{authClient}； const getAuth = createServerFn({ 方法: "GET" }).handler(async () => { 返回等待 getToken(); }); 导出常量路由 = createRootRouteWithContext<{ 查询客户端：查询客户端；凸查询客户端：凸查询客户端； }>()({ beforeLoad: async (ctx) => { const token = 等待 getAuth(); 如果（令牌）{ ctx.context.convexQueryClient.serverHttpClient?.setAuth(token); } 返回 { isAuthenticated:!!token, token }; }, 组件：根组件， }); 函数根组件（）{ const {凸查询客户端，令牌} = Route.useRouteContext(); 返回（ <出口/> ）； } ### 5\.受保护的路由守卫 **src/routes/_authed.tsx** 从“@tanstack/react-router”导入{createFileRoute，Outlet，redirect}；导出 const 路由 = createFileRoute("/_authed")({ 加载前: ({ 上下文 }) => { if (!context.isAuthenticated) { 抛出重定向（{至：“/登录”}）； } }, 组件：() => , }); ### 6\.投票配置 **vite.config.ts** 从“vite”导入{defineConfig}；从“@tanstack/react-start/plugin/vite”导入{ tanstackStart }；从“@vitejs/plugin-react”导入反应；从“@tailwindcss/vite”导入 tailwindcss；从“路径”导入路径；导出默认的defineConfig({ 插件：[tanstackStart()、react()、tailwindcss()]、解决：{ 别名: { "@": path.resolve(__dirname, "./src") }, }, SSR：{ // 必需：在 SSR 期间捆绑 @convex-dev/better-auth noExternal：[“@convex-dev/better-auth”]， }, }); ### 7\.路由器配置 **src/router.tsx** 从“@tanstack/react-router”导入{createRouter}；从“./routeTree.gen”导入{routeTree}；从“@tanstack/react-query”导入{QueryClient}；从“@convex-dev/react-query”导入{ConvexQueryClient}；从“凸/反应”导入{ConvexReactClient}； const 凸 = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL); 导出函数createAppRouter() { const queryClient = new QueryClient(); const convexQueryClient = new ConvexQueryClient(凸, { ExpectAuth: true }); queryClient.setDefaultOptions({ 查询：{queryKeyHashFn：凸查询Client.hashFn（）}， }); 凸查询客户端.connect(queryClient); 返回创建路由器（{ 路线树，上下文：{queryClient，凸查询客户端}，默认预加载：“意图”， }); } ## 环境变量 **.env.local** # 凸部署（由`npx凸开发`设置） CONVEX_DEPLOYMENT=dev:您的部署 VITE_CONVEX_URL=https://your-deployment.convex.cloud VITE_CONVEX_SITE_URL=https://your-deployment.convex.site # 应用程序网址 VITE_SITE_URL=http://localhost:3000 **凸环境变量**（通过 CLI 设置）： # 生成并设置秘密 npx 凸环境集 BETTER_AUTH_SECRET=$(openssl rand -base64 32) # 设置站点 URL npx 凸环境集 SITE_URL http://localhost:3000 # OAuth（可选） npx 凸 env 设置 GITHUB_CLIENT_ID 你的 id npx 凸 env 设置 GITHUB_CLIENT_SECRET 你的秘密 ## 常见模式 ### 受保护的查询 //凸/todos.ts 从“./_ generated/server”导入{查询，突变}；从“凸/值”导入 { v }；从“./auth”导入{ getUser，safeGetUser }；导出 const get = 查询({ 处理程序：异步（ctx）=> { const user = 等待 safeGetUser(ctx); 如果（！用户）返回[]； return ctx.db.query("todos").withIndex("userId", (q) => q.eq("userId", user._id)).collect(); }, }); 导出常量创建=突变（{ args: { 文本: v.string() }, 处理程序： async (ctx, args) => { const user = 等待 getUser(ctx); // 如果未验证则抛出异常等待 ctx.db.insert("todos", { 文本: args.text, userId: user._id, 完成: false }); }, }); ### 登录组件从“~/lib/auth-client”导入{authClient}；从“~/components/ui/button”导入{Button}；从“~/components/ui/input”导入{输入}；导出函数 SignIn() { const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); const form = new FormData(e.currentTarget); 等待 authClient.signIn.email({ 电子邮件： form.get("email") 作为字符串，密码： form.get("password") 作为字符串， }); }; 返回（

<输入名称=“电子邮件”类型=“电子邮件”占位符=“电子邮件”必需/> <输入名称=“密码”类型=“密码”占位符=“密码”必需/> ; } ## TanStack 服务器函数与凸函数：何时使用什么使用案例|使用这个 |为什么 ---|---|--- 数据库增删改查 | **凸查询/变异** |交易性、实时性实时数据 | **凸查询** |自动订阅第三方API | **凸作用** |运行接近数据身份验证处理程序 | **TanStack 服务器路由** | HTTP cookie/重定向 SSR预加载| **TanStack 加载程序** | SSR 预取网络钩子 | **TanStack 服务器路由** | HTTP 端点 **核心原则：** 凸=数据库&业务逻辑。 TanStack Start = HTTP 和渲染。有关详细指南，请参阅“reference/server-functions-vs-convex.md”。 ## 关键集成点整合|密钥文件 |目的 ---|---|--- 身份验证客户端 | `src/lib/auth-client.tsx` |客户端验证方法认证服务器 | `src/lib/auth-server.ts` | SSR 令牌处理根提供者 | `src/routes/__root.tsx` |身份验证上下文 + 凸客户端路线守卫 | `src/routes/_authed.tsx` |重定向未经身份验证的用户后端验证 | `凸/auth.ts` |更好的验证实例 HTTP 路由 | `凸/http.ts` |身份验证端点注册数据库| `凸/schema.ts` |类型安全模式

Tcbs堆栈

包含技能