betterauth-tanstack-convex

Better Auth + Convex + TanStack Start

概述

本技能为将 Better Auth 身份验证与 Convex 后端及 TanStack Start 框架集成提供指导。它涵盖了从安装到兼容 SSR 的身份验证流程的完整设置过程。

何时使用本技能

• 在新的 Convex + TanStack Start 项目中设置身份验证
• 排查 Better Auth 配置问题
• 实现注册、登录或登出流程
• 使用 expectAuth: true 配置 SSR 身份验证
• 添加需要身份验证的服务端函数
• 理解身份验证提供程序层级

快速参考

所需包

npm install convex@latest @convex-dev/better-auth
npm install [email protected] --save-exact
npm install @types/node --save-dev

环境变量

Convex 部署（通过命令行）：

npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
npx convex env set SITE_URL http://localhost:3000

.env.local：

CONVEX_DEPLOYMENT=dev:adjective-animal-123
VITE_CONVEX_URL=https://adjective-animal-123.convex.cloud
VITE_CONVEX_SITE_URL=https://adjective-animal-123.convex.site
VITE_SITE_URL=http://localhost:3000

文件结构

文件	用途
convex/convex.config.ts	注册 Better Auth 组件
convex/auth.config.ts	配置身份验证提供程序
convex/auth.ts	创建 Better Auth 实例 + authComponent
convex/http.ts	注册身份验证 HTTP 路由
src/lib/auth-client.ts	客户端身份验证工具
src/lib/auth-server.ts	服务端身份验证工具
src/routes/api/auth/$.ts	将身份验证请求代理到 Convex
src/routes/__root.tsx	身份验证提供程序包装器 + SSR token

必要导入

// Client-side
import { authClient } from '~/lib/auth-client'

// Server-side
import { getToken, fetchAuthQuery, fetchAuthMutation } from '~/lib/auth-server'

// Backend
import { authComponent, createAuth } from './auth'

身份验证检查（后端）

const user = await authComponent.getAuthUser(ctx)
if (!user) throw new Error("Not authenticated")

使用 expectAuth 登出

使用 expectAuth: true 时，登出后重新加载页面：

await authClient.signOut({
  fetchOptions: {
    onSuccess: () => location.reload(),
  },
})

关键配置

Vite SSR Bundle

需要在 vite.config.ts 中配置，以避免模块解析问题：

ssr: {
  noExternal: ['@convex-dev/better-auth'],
}

带 expectAuth 的 ConvexQueryClient

为实现无缝 SSR 身份验证所必需：

const convexQueryClient = new ConvexQueryClient(convexUrl, {
  expectAuth: true,
})

提供程序层级

根组件必须按以下顺序包装子组件：

1. ConvexBetterAuthProvider（最外层）
2. QueryClientProvider
3. 带 <Outlet /> 的 RootDocument

参考文件

在实现身份验证时加载详细的设置指南：

文件	使用时机
references/setup-guide.md	完整的逐步安装和配置