@better-auth-ui/react 1.6.3 → 1.6.5

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@better-auth-ui/react",
-  "version": "1.6.3",
+  "version": "1.6.5",
   "type": "module",
   "scripts": {
     "build": "vite build",
-    "dev": "tsc --watch",
-    "email": "email dev --dir src/components/email -p 9000",
+    "dev": "vite build --watch",
+    "email": "email dev --dir src/components/auth/email -p 9000",
     "test": "vitest"
   },
   "files": [
@@ -19,46 +19,52 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./core": {
-      "types": "./dist/core.d.ts",
-      "import": "./dist/core.js"
+    "./email": {
+      "types": "./dist/email.d.ts",
+      "import": "./dist/email.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins.d.ts",
+      "import": "./dist/plugins.js"
     }
   },
   "devDependencies": {
+    "@better-auth/passkey": "^1.6.9",
     "@react-email/components": "^1.0.12",
     "@react-email/preview-server": "^5.2.10",
-    "@tanstack/react-query": "^5.99.0",
+    "@tanstack/react-query": "^5.100.8",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.5.2",
     "@types/react": "^19.2.14",
     "@vitejs/plugin-react": "^6.0.1",
-    "@vitest/browser-playwright": "^4.1.4",
-    "@better-auth/passkey": "^1.6.5",
-    "better-auth": "^1.6.5",
+    "@vitest/browser-playwright": "^4.1.5",
+    "better-auth": "^1.6.9",
     "clsx": "^2.1.1",
     "playwright": "^1.59.1",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "react-email": "^6.0.0",
+    "react-email": "^6.0.5",
     "tailwind-merge": "^3.5.0",
-    "tailwindcss": "^4.2.2",
-    "vitest": "^4.1.4",
-    "zod": "^4.3.6"
-  },
-  "dependencies": {
-    "@better-auth-ui/core": "*"
+    "tailwindcss": "^4.2.4",
+    "vitest": "^4.1.5",
+    "zod": "^4.4.2"
   },
   "peerDependencies": {
+    "@better-auth-ui/core": "*",
+    "@better-auth/passkey": ">=1.6.9",
     "@react-email/components": ">=1.0.12",
-    "@tanstack/react-query": ">=5.99.0",
-    "@better-auth/passkey": ">=1.6.5",
-    "better-auth": ">=1.6.5",
+    "@tanstack/react-query": ">=5.100.8",
+    "better-auth": ">=1.6.9",
     "clsx": ">=2.0.0",
     "react": ">=19.2.5",
     "react-dom": ">=19.2.5",
     "tailwind-merge": ">=3.5.0",
-    "tailwindcss": ">=4.2.2",
-    "zod": ">=4.3.0"
+    "tailwindcss": ">=4.2.4",
+    "zod": ">=4.4.2"
   },
   "repository": {
     "type": "git",

package/src/components/auth/auth-provider.tsx

@@ -1,30 +1,57 @@
 "use client"
 
-import { deepmerge, defaultAuthConfig } from "@better-auth-ui/core"
+import {
+  type AdditionalField,
+  type AuthConfig,
+  type DeepPartial,
+  deepmerge,
+  defaultAuthConfig
+} from "@better-auth-ui/core"
 import {
   QueryClient,
   QueryClientContext,
   QueryClientProvider
 } from "@tanstack/react-query"
-import { type PropsWithChildren, useContext } from "react"
+import {
+  createContext,
+  type PropsWithChildren,
+  type ReactNode,
+  useContext
+} from "react"
+import type { AuthClient } from "../../lib/auth-client"
+import { FetchOptionsProvider } from "./fetch-options-provider"
 
-import type { AnyAuthClient } from "../../lib/auth-client"
-import type { AnyAuthConfig, AuthConfig } from "../../lib/auth-config"
-import { AuthContext } from "../../lib/auth-context"
+const AuthContext = createContext<AuthConfig | undefined>(undefined)
+
+const fallbackQueryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5000
+    }
+  }
+})
 
-const fallbackQueryClient = new QueryClient()
+declare module "@better-auth-ui/core" {
+  interface AuthConfig {
+    /**
+     * The auth client to use for the authentication context.
+     * @remarks `AuthClient`
+     */
+    authClient: AuthClient
+  }
 
-const baseAuthConfig: AnyAuthConfig = {
-  ...defaultAuthConfig,
-  Link: (props) => <a {...props} />
+  /** Widen `AdditionalField.label` to `ReactNode` in the React package. */
+  interface AdditionalFieldRegister {
+    label: ReactNode
+  }
 }
 
-export type AuthProviderProps = PropsWithChildren<AnyAuthConfig> & {
-  authClient: AnyAuthClient
+export type AuthProviderProps<TAuthClient = AuthClient> = PropsWithChildren<
+  DeepPartial<AuthConfig>
+> & {
+  authClient: TAuthClient
   navigate: (options: { to: string; replace?: boolean }) => void
-  /**
-   * TanStack QueryClient to use for your application's queries
-   */
+  /** TanStack QueryClient to use for your application's queries */
   queryClient?: QueryClient
 }
 
@@ -43,33 +70,69 @@ export function AuthProvider({
   queryClient,
   ...config
 }: AuthProviderProps) {
-  const contextQueryClient = useContext(QueryClientContext)
-  const resolvedQueryClient =
-    queryClient || contextQueryClient || fallbackQueryClient
-
-  const mergedConfig = deepmerge(baseAuthConfig, config) as AuthConfig
+  const mergedConfig = deepmerge(defaultAuthConfig, {
+    ...config,
+    viewPaths: {
+      auth: {
+        ...defaultAuthConfig.viewPaths.auth,
+        ...config.viewPaths?.auth
+      },
+      settings: {
+        ...defaultAuthConfig.viewPaths.settings,
+        ...config.viewPaths?.settings
+      }
+    }
+  } as AuthConfig)
 
   mergedConfig.redirectTo =
     (typeof window !== "undefined" &&
       new URLSearchParams(window.location.search).get("redirectTo")?.trim()) ||
     mergedConfig.redirectTo
 
+  // Merge plugin-contributed `additionalFields` with user-supplied ones.
+  // Plugin order is preserved; user-supplied entries with the same `name`
+  // override the plugin contribution.
+  const fieldsByName = new Map<string, AdditionalField>()
+  for (const plugin of mergedConfig.plugins ?? []) {
+    for (const field of plugin.additionalFields ?? []) {
+      fieldsByName.set(field.name, field)
+    }
+  }
+  for (const field of mergedConfig.additionalFields ?? []) {
+    fieldsByName.set(field.name, field)
+  }
+  mergedConfig.additionalFields = Array.from(fieldsByName.values())
+
+  const contextQueryClient = useContext(QueryClientContext)
+
+  if (contextQueryClient) {
+    return (
+      <AuthContext.Provider value={mergedConfig}>
+        <FetchOptionsProvider>{children}</FetchOptionsProvider>
+      </AuthContext.Provider>
+    )
+  }
+
   return (
-    <AuthContext.Provider value={mergedConfig}>
-      <QueryClientProvider client={resolvedQueryClient}>
-        {children}
-      </QueryClientProvider>
-    </AuthContext.Provider>
+    <QueryClientProvider client={queryClient || fallbackQueryClient}>
+      <AuthContext.Provider value={mergedConfig}>
+        <FetchOptionsProvider>{children}</FetchOptionsProvider>
+      </AuthContext.Provider>
+    </QueryClientProvider>
   )
 }
 
 /**
  * Accesses the current authentication configuration from AuthContext.
  *
+ * UI packages widen the plugin type globally via the `Register` interface
+ * (see module augmentation in `@better-auth-ui/heroui`), so callers don't
+ * need to pass a generic.
+ *
  * @returns The merged authentication configuration provided by AuthProvider.
  * @throws If no AuthProvider is present in the component tree.
  */
-export function useAuth() {
+export function useAuth(): AuthConfig {
   const context = useContext(AuthContext)
 
   if (!context) {

package/src/components/{email → auth/email}/email-changed.tsx

@@ -16,7 +16,7 @@ import {
 } from "@react-email/components"
 import type { ReactNode } from "react"
 
-import { cn } from "../../lib/utils"
+import { cn } from "../../../lib/utils"
 import {
   type EmailClassNames,
   type EmailColors,

package/src/components/{email → auth/email}/email-verification.tsx

@@ -16,7 +16,7 @@ import {
 } from "@react-email/components"
 import type { ReactNode } from "react"
 
-import { cn } from "../../lib/utils"
+import { cn } from "../../../lib/utils"
 import {
   type EmailClassNames,
   type EmailColors,

package/src/components/{email → auth/email}/magic-link.tsx

@@ -16,7 +16,7 @@ import {
 } from "@react-email/components"
 import type { ReactNode } from "react"
 
-import { cn } from "../../lib/utils"
+import { cn } from "../../../lib/utils"
 import {
   type EmailClassNames,
   type EmailColors,

package/src/components/{email → auth/email}/new-device.tsx

@@ -16,7 +16,7 @@ import {
 } from "@react-email/components"
 import type { ReactNode } from "react"
 
-import { cn } from "../../lib/utils"
+import { cn } from "../../../lib/utils"
 import {
   type EmailClassNames,
   type EmailColors,

package/src/components/{email → auth/email}/otp-email.tsx

@@ -15,7 +15,7 @@ import {
 } from "@react-email/components"
 import type { ReactNode } from "react"
 
-import { cn } from "../../lib/utils"
+import { cn } from "../../../lib/utils"
 import {
   type EmailClassNames,
   type EmailColors,

package/src/components/{email → auth/email}/password-changed.tsx

@@ -16,7 +16,7 @@ import {
 } from "@react-email/components"
 import type { ReactNode } from "react"
 
-import { cn } from "../../lib/utils"
+import { cn } from "../../../lib/utils"
 import {
   type EmailClassNames,
   type EmailColors,

package/src/components/{email → auth/email}/reset-password.tsx

@@ -16,7 +16,7 @@ import {
 } from "@react-email/components"
 import type { ReactNode } from "react"
 
-import { cn } from "../../lib/utils"
+import { cn } from "../../../lib/utils"
 import {
   type EmailClassNames,
   type EmailColors,

package/src/components/auth/fetch-options-provider.tsx

@@ -0,0 +1,77 @@
+"use client"
+
+import {
+  createContext,
+  type PropsWithChildren,
+  useCallback,
+  useContext,
+  useRef,
+  useState
+} from "react"
+
+/** Subset of BetterFetchOptions we expose. Add fields as use-cases arise. */
+export type FetchOptions = {
+  headers?: Record<string, string>
+  body?: Record<string, unknown>
+}
+
+type FetchOptionsContextValue = {
+  /** Current fetchOptions, or `undefined` when none are set. */
+  fetchOptions: FetchOptions | undefined
+  /** OVERRIDES the entire fetchOptions object. Pass `undefined` to clear. */
+  setFetchOptions: (fetchOptions: FetchOptions | undefined) => void
+  /** Clears `fetchOptions` and runs the registered reset (e.g. captcha widget). Call from form `onError`. */
+  resetFetchOptions: () => void
+  /** Register a reset handler. Used by `captchaPlugin`. Pass `null` to clear. */
+  registerReset: (reset: (() => void) | null) => void
+}
+
+const FetchOptionsContext = createContext<FetchOptionsContextValue | undefined>(
+  undefined
+)
+
+export function FetchOptionsProvider({ children }: PropsWithChildren) {
+  const [current, setCurrent] = useState<FetchOptions | undefined>(undefined)
+  const resetRef = useRef<(() => void) | null>(null)
+
+  const setFetchOptions = useCallback(
+    (fetchOptions: FetchOptions | undefined) => {
+      setCurrent(fetchOptions)
+    },
+    []
+  )
+
+  const registerReset = useCallback((reset: (() => void) | null) => {
+    resetRef.current = reset
+  }, [])
+
+  const resetFetchOptions = useCallback(() => {
+    setCurrent(undefined)
+    resetRef.current?.()
+  }, [])
+
+  return (
+    <FetchOptionsContext.Provider
+      value={{
+        fetchOptions: current,
+        setFetchOptions,
+        resetFetchOptions,
+        registerReset
+      }}
+    >
+      {children}
+    </FetchOptionsContext.Provider>
+  )
+}
+
+export function useFetchOptions(): FetchOptionsContextValue {
+  const ctx = useContext(FetchOptionsContext)
+
+  if (!ctx) {
+    throw new Error(
+      "[Better Auth UI] useFetchOptions must be used within FetchOptionsProvider"
+    )
+  }
+
+  return ctx
+}

package/src/email.ts

@@ -0,0 +1 @@
+export * from "./components/auth/email"

package/src/hooks/auth/use-authenticate.ts

@@ -1,18 +1,24 @@
 import { useEffect } from "react"
 import { useAuth } from "../../components/auth/auth-provider"
-import { type UseSessionOptions, useSession } from "./use-session"
+import type { AuthClient } from "../../lib/auth-client"
+import {
+  type UseSessionOptions,
+  useSession
+} from "../../queries/auth/session-query"
 
 /**
  * Calls `useSession` and redirects unauthenticated users to the sign-in page,
  * preserving the current URL as a `redirectTo` query param.
  *
- * @param options - Better Auth params (`query`, `fetchOptions`) and React
- *   Query options forwarded to `useQuery`.
- * @returns React Query result for the session.
+ * @param authClient - The Better Auth client.
+ * @param options - `getSession` params & `useQuery` options.
  */
-export function useAuthenticate(options?: UseSessionOptions) {
+export function useAuthenticate<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: UseSessionOptions<TAuthClient>
+) {
   const { basePaths, viewPaths, navigate } = useAuth()
-  const session = useSession(options)
+  const session = useSession(authClient, options)
 
   useEffect(() => {
     if (session.data || session.isPending) return

package/src/hooks/auth/use-user.ts

@@ -1,16 +1,21 @@
-import { type UseSessionOptions, useSession } from "./use-session"
+import type { AuthClient } from "../../lib/auth-client"
+import {
+  type UseSessionOptions,
+  useSession
+} from "../../queries/auth/session-query"
 
 /**
- * Retrieve the current authenticated user.
+ * Retrieve the current authenticated user. Thin wrapper over `useSession`
+ * that returns `session.user` as `data`.
  *
- * Thin wrapper over `useSession` that returns `session.user` as `data`.
- *
- * @param options - Better Auth params (`query`, `fetchOptions`) and React
- *   Query options forwarded to `useQuery`.
- * @returns React Query result with `data` narrowed to the user object.
+ * @param authClient - The Better Auth client.
+ * @param options - `getSession` params & `useQuery` options.
  */
-export function useUser(options?: UseSessionOptions) {
-  const { data, ...rest } = useSession(options)
+export function useUser<TAuthClient extends AuthClient>(
+  authClient: TAuthClient,
+  options?: UseSessionOptions<TAuthClient>
+) {
+  const { data, ...rest } = useSession(authClient, options)
 
   return {
     data: data?.user,

package/src/hooks/use-auth-mutation.ts

@@ -1,26 +1,44 @@
-import { type MutationKey, useMutation } from "@tanstack/react-query"
-import { authMutationOptions } from "../mutations/auth-mutation-options"
+import {
+  type MutationKey,
+  type UseMutationOptions,
+  useMutation
+} from "@tanstack/react-query"
+import type { BetterFetchError } from "better-auth/client"
+
+import {
+  type AuthMutationFn,
+  type AuthMutationFnData,
+  type AuthMutationFnVariables,
+  authMutationOptions
+} from "../mutations/auth-mutation-options"
+
+type UseAuthMutationOptions<TFn extends AuthMutationFn> = Omit<
+  UseMutationOptions<
+    AuthMutationFnData<TFn>,
+    BetterFetchError,
+    AuthMutationFnVariables<TFn>
+  >,
+  "mutationKey" | "mutationFn"
+>
 
 /**
- * Escape-hatch hook for Better Auth endpoints that don't have a purpose-built
- * mutation hook in this library yet. Thin wrapper over `useMutation` and
- * `authMutationOptions`.
+ * Escape-hatch hook for Better Auth write endpoints that don't have a
+ * purpose-built mutation hook in this library yet. Thin wrapper over
+ * `useMutation` and `authMutationOptions`.
  *
  * @param authFn - Better Auth client method (e.g. `authClient.emailOtp.sendVerificationOtp`).
- * @param mutationKey - Scope for the mutation cache key.
+ * @param mutationKey - Stable key for the mutation. Prefer an entry from
+ *   `authMutationKeys` over an inline tuple so `useIsMutating` and global
+ *   `MutationCache` observers line up.
  * @param options - React Query options forwarded to `useMutation`.
  */
 export function useAuthMutation<
-  // biome-ignore lint/suspicious/noExplicitAny: matches authMutationOptions' widened constraint
-  TFn extends (...args: any) => any,
+  TFn extends AuthMutationFn,
   const TMutationKey extends MutationKey
 >(
   authFn: TFn,
   mutationKey: TMutationKey,
-  options?: Omit<
-    ReturnType<typeof authMutationOptions<TFn, TMutationKey>>,
-    "mutationKey" | "mutationFn"
-  >
+  options?: UseAuthMutationOptions<TFn>
 ) {
   return useMutation({
     ...authMutationOptions(authFn, mutationKey),

package/src/hooks/use-auth-plugin.ts

@@ -0,0 +1,50 @@
+"use client"
+
+import { useAuth } from "../components/auth/auth-provider"
+import type { AuthPlugin } from "../lib/auth-plugin"
+
+/**
+ * Plugin factory shape accepted by {@link useAuthPlugin}. The `id` is read as
+ * a static property — the factory is never invoked — so plugins with required
+ * options (e.g. `themePlugin`'s `setTheme`) can still be looked up.
+ *
+ * Always produced by `createAuthPlugin` from `@better-auth-ui/core`.
+ */
+export type AuthPluginFactory<T extends AuthPlugin = AuthPlugin> = {
+  id: string
+  // biome-ignore lint/suspicious/noExplicitAny: factory args vary by plugin
+  (...args: any[]): T
+}
+
+/**
+ * Access a registered plugin by passing its factory.
+ *
+ * Use inside plugin slot components to read plugin state (localization,
+ * config, etc.) without prop drilling.
+ *
+ * Throws if the plugin isn't registered on `AuthProvider` — this is an
+ * invariant: plugin slot components only render when their plugin is in
+ * `plugins`.
+ *
+ * @example
+ * ```tsx
+ * function PasskeyButton() {
+ *   const { localization } = useAuthPlugin(passkeyPlugin)
+ *   return <button>{localization.passkey}</button>
+ * }
+ * ```
+ */
+export function useAuthPlugin<T extends AuthPlugin>(
+  pluginFactory: AuthPluginFactory<T>
+): T {
+  const { plugins } = useAuth()
+  const plugin = plugins?.find((p) => p.id === pluginFactory.id)
+
+  if (!plugin) {
+    throw new Error(
+      `[Better Auth UI] useAuthPlugin: plugin "${pluginFactory.id}" is not registered on AuthProvider.`
+    )
+  }
+
+  return plugin as T
+}

package/src/hooks/use-auth-query.ts

@@ -1,11 +1,15 @@
 import { type QueryKey, useQuery } from "@tanstack/react-query"
-import { type AuthFn, authQueryOptions } from "../queries/auth-query-options"
+import {
+  type AuthQueryFn,
+  type AuthQueryOptions,
+  authQueryOptions
+} from "../queries/auth-query-options"
 
-type UseAuthQueryOptions<TFn extends AuthFn, TQueryKey extends QueryKey> = Omit<
-  ReturnType<typeof authQueryOptions<TFn, TQueryKey>>,
-  "queryKey" | "queryFn"
-> &
-  NonNullable<Parameters<TFn>[0]>
+type UseAuthQueryOptions<
+  TFn extends AuthQueryFn,
+  TPrefix extends QueryKey
+> = Omit<AuthQueryOptions<TFn, TPrefix>, "queryKey" | "queryFn"> &
+  Pick<NonNullable<Parameters<TFn>[0]>, "query" | "fetchOptions">
 
 /**
  * Escape-hatch hook for Better Auth endpoints that don't have a purpose-built
@@ -17,7 +21,7 @@ type UseAuthQueryOptions<TFn extends AuthFn, TQueryKey extends QueryKey> = Omit<
  *   Query options forwarded to `useQuery`.
  */
 export function useAuthQuery<
-  TFn extends AuthFn,
+  TFn extends AuthQueryFn,
   const TQueryKey extends QueryKey
 >(
   authFn: TFn,