SSR 认证最佳实践：Convex + Better Auth 在 Next.js 与 TanStack Start 中的服务端渲染攻略
SSR 认证最佳实践Convex Better Auth 在 Next.js 与 TanStack Start 中的服务端渲染攻略【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth当用户请求到达服务端时你的页面是否还在闪一下白屏才显示登录状态SSR 认证服务端渲染认证正是解决这一痛点的关键。Better Auth作为新一代全栈认证库配合Convex实时后端为 Next.js 与 TanStack Start 提供了开箱即用的服务端渲染认证方案数据在服务端预取、令牌随请求传递、受保护路由在渲染前拦截。本文将用最少的代码带你掌握这套Convex Better Auth 服务端渲染最佳实践从零搭建安全且快速的 SSR 认证体系。为什么 SSR 认证需要双重服务端认证库服务端 数据库服务端各自扮演什么角色传统 JWT 方案中客户端持有令牌、每次请求手动携带极易出现令牌泄漏与闪烁。而 Better Auth 与 Convex 的组合把认证彻底前移到服务端Better Auth负责签发会话、校验令牌、管理用户与 OAuth 流程其 HTTP 接口以handler形式挂在你的应用路由上Convex作为后端数据库与函数运行时提供fetchAuthQuery/fetchAuthMutation等能力让服务端直接读取当前用户数据两者通过convex-dev/better-auth桥接层无缝协作令牌在请求头中流转页面在服务端就能完成身份判定。 一句话概括认证逻辑在服务端完成用户数据也在服务端读取浏览器只负责渲染最终 HTML。第一步在 Convex 中初始化认证组件无论前端框架如何后端都共享同一套初始化代码。在convex/auth.ts中创建认证组件并配置插件export const authComponent createClientDataModel, typeof authSchema( components.betterAuth, { local: { schema: authSchema } }, ); export const createAuthOptions (ctx) ({ baseURL: siteUrl, database: authComponent.adapter(ctx), emailAndPassword: { enabled: true }, plugins: [anonymous(), magicLink({...}), twoFactor(), convex({ authConfig })], });参考实现见 examples/next/convex/auth.ts 与 examples/tanstack/convex/auth.ts两套示例的后端结构完全一致前端只需换适配层。第二步Next.js 中的 SSR 认证四步走挂载认证 Handler接管所有 /api/auth 请求在app/api/auth/[...all]/route.ts中导出handlerBetter Auth 的全部接口注册、登录、会话都会经过这里import { handler } from /lib/auth-server; export const { GET, POST } handler;用 getToken 把身份令牌注入全局 Provider在根布局app/layout.tsx中读取令牌并传给 Convex 客户端服务端渲染时 Convex 就能识别我是谁const token await getToken(); // ConvexProvider ... client{convex}ConvexAuthProvider token{token}...用 isAuthenticated 在渲染前拦截路由受保护区域与公开区域各用一个布局在组件渲染之前完成重定向从根源杜绝未登录内容闪烁// app/(auth)/layout.tsx —— 需登录 if (!(await isAuthenticated())) redirect(/sign-in); // app/(unauth)/layout.tsx —— 需登出 if (await isAuthenticated()) redirect(/dashboard);完整示例见 examples/next/app/(auth)/layout.tsx/layout.tsx)。用 preloadAuthQuery 预取用户数据页面级 SSR 的关键一步在服务端并行预加载用户与业务数据客户端用usePreloadedAuthQuery直接消费首屏即见const [user, todos] await Promise.all([ preloadAuthQuery(api.auth.getCurrentUser), preloadAuthQuery(api.todos.get), ]);参考 examples/next/app/(auth)/(dashboard)/page.tsx/(dashboard)/page.tsx) 与 header.tsx/(dashboard)/header.tsx)。第三步TanStack Start 中的 SSR 认证同样简单TanStack Start 使用convexBetterAuthReactStart适配层核心思路完全一致见 examples/tanstack/src/lib/auth-server.ts。用 server handler 接管认证路由在src/routes/api/auth/$.ts中把请求转发给 Better Authserver: { handlers: { GET: ({request}) handler(request), POST: ... } }用 beforeLoad 守卫路由并预取数据TanStack Router 的优势是路由级认证守卫在_authed.tsx的beforeLoad中检查context.isAuthenticated不通过直接redirect(/sign-in)随后在页面 loader 中用ensureQueryData预取查询见 examples/tanstack/src/routes/_authed.tsx 与 index.tsx。第四步客户端 AuthBoundary 兜底双保险即使服务端已拦截客户端仍建议包一层AuthBoundary当 token 失效时自动跳转登录页形成服务端守卫 客户端兜底的双保险见 examples/next/lib/auth-client.tsxAuthBoundary authClient{authClient} getAuthUserFn{api.auth.getAuthUser} onUnauth{() router.push(/sign-in)} {children} /AuthBoundary进阶启用 JWT 缓存让页面加载再快一步官方示例中还提供了实验性的jwtCache选项开启后服务端可直接用缓存的 JWT 判定身份省去每次查询数据库的开销尤其适合高频访问的 SSR 页面jwtCache: { enabled: true, isAuthError }配置位置见 examples/next/lib/auth-server.ts。两个框架的完整可运行示例分别位于 examples/next 与 examples/tanstack可 clone 仓库https://gitcode.com/gh_mirrors/con/better-auth后对照阅读。总结SSR 认证最佳实践的四个关键词能力Next.jsTanStack Start认证入口handler(route.ts)handler(server handlers)身份令牌getTokengetToken路由守卫isAuthenticated(layout)context.isAuthenticated(beforeLoad)数据预取preloadAuthQueryensureQueryData掌握这四组 API你就能在 Next.js 与 TanStack Start 中实现无闪烁、更安全、更快的 SSR 认证体验。服务端渲染认证的核心就是把我是谁这件事在 HTML 产出之前解决掉——而 Convex Better Auth 已经帮你把整条链路都铺好了。【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
