better-auth-ui-react

用于 React 的 Better Auth UI

以已安装软件包的导出内容为 API 版本的权威依据。本指南涵盖 1.7 软件包结构。

选择 UI

• 对于复制的 shadcn/ui 组件，请阅读 shadcn 集成。
• 对于打包的 HeroUI 组件，请使用 @better-auth-ui/heroui，并在可用时使用其 better-auth-ui-heroui 技能。
• 对于自定义界面，请直接使用 @better-auth-ui/react 中的提供器和 Hooks。

@better-auth-ui/react 是共享数据层。它不会导出复制的 shadcn Auth、Settings 或 UserButton 组件。

配置应用程序

1. 配置 Better Auth，并在应用程序的服务端路由中挂载其处理程序。
2. 使用 better-auth/react 中的 createAuthClient 创建 React 客户端。
3. 使用所选 UI 的 AuthProvider 包裹身份验证使用方。
4. 传入 authClient、兼容路由器的 navigate，以及应用程序的 queryClient。
5. 配置重定向目标、UI 路径和插件，使其与应用程序的路由相匹配。

导航回调接收 { to, replace? }。应将 Next.js router.push 和 router.replace 适配为此对象，而不是直接传入。

React 提供器会优先选择显式传入的 QueryClient，其次是现有的 Query 上下文，最后是备用项。对于 SSR，请传入请求作用域的客户端。

在 Next.js 中，为交互式提供器和 Hooks 使用客户端边界。将服务端配置、密钥和 /server 导入放在这些边界之外。

读取和更改身份验证数据

import { useSession, useSignInEmail } from "@better-auth-ui/react"

const session = useSession(authClient, { staleTime: 5_000 })
const signIn = useSignInEmail(authClient)

在 React 组件或自定义 Hook 中调用这些 Hooks。请显式提供身份验证客户端。

查询会公开 TanStack Query 状态，例如 data、isPending 和 error。变更会公开 mutate、mutateAsync 和 isPending。

当使用方共享 Better Auth UI 的 Query 缓存时，请使用 useSession。Better Auth 自带的 authClient.useSession() 使用不同的订阅路径。

从 @better-auth-ui/react/plugins/<plugin> 导入可选 Hooks。从 @better-auth-ui/core 或其插件入口点导入加载器工厂和辅助函数。

在查询完成前，保持页面标题、导航和独立内容处于挂载状态。仅对尚未解析的值和依赖操作显示待处理状态。

加载器和 SSR

浏览器加载器请使用 ensureSession(queryClient, authClient)。服务端请使用 @better-auth-ui/core/server 中的 ensureSessionServer(queryClient, auth, { headers })。

每个服务端请求都创建一个 QueryClient。将同一个客户端传给加载器、水合过程和 AuthProvider。

对于 TanStack Start，请使用文档所述的 Router/Query SSR 集成。对于 Next.js，请将直接服务端调用保留在仅服务端代码中。

不要在模块级服务端 QueryClient 中缓存某个用户的会话。除了路由守卫，还要在服务端端点中强制执行权限检查。

插件和组织

适用时，请在三个位置启用每项功能：Better Auth 服务端、其客户端插件，以及所选 UI 插件。

使用所选组件系统提供的 UI 插件。核心插件提供共享行为，但不会提供复制的 UI 视图。

将插件视图路径纳入路由验证。写死的基础身份验证路径可能会拒绝有效的邀请或双重验证路由。

从路由 slug 或显式 ID 中选择组织。传入 organizationPlugin({ slug })；个人账户路由使用 null。

路由更改时，请保持此值为最新值。不要将会话中的活动组织状态或 setActive 用作访问权限的依据。

参考资料

• React 查询
• React 变更
• React SSR
• shadcn Next.js 集成
• shadcn TanStack Start 集成
• 文档索引

网站示例基于当前版本。使用较新文档中的 API 前，请先检查已安装的软件包。