skills/plugins/document-navigator/docs/ui/react/react-auth

@suaveplan/react-auth - React authentication core: Better-Auth client wrapper, AuthProvider context, AuthGuard, useAuthGuard/usePermission hooks, locale packs.

React authentication core for Suaveplan apps — a typed wrapper around better-auth/client, an AuthProvider React context, an AuthGuard route component, useAuthGuard and usePermission hooks, a betterAuthAdapter response bridge, OTel instruments, a REACT_AUTH_CODES error registry, and shipped translation packs for en-GB, cy-GB, and zh-CN. Wave 1 (this package) ships the foundational core that downstream packages (the parallel react-auth-whitelabel, and consumer apps) build on; form components (Wave 2) and page components (Wave 3) layer on top without changing this surface.

Documentation tree

• client — auth-client.ts ships a typed AuthClient class plus the createAuthClient(config) factory that wraps `better-auth/c…
  • auth-client — auth-client.ts ships a typed AuthClient class plus the createAuthClient(config) factory that wraps `better-auth/c…
• components — Internal test helper consumed only by the Wave 2 form .test.tsx files in src/components/<form>/. The helper wraps a…
  • auth-guard — <AuthGuard> is the declarative route gate. It reads the current auth state from the surrounding AuthProvider, evalu…
    • auth-guard — <AuthGuard> is the declarative route gate. It reads the current auth state from the surrounding AuthProvider, evalu…
  • auth-provider — auth-provider.tsx is a thin back-compatibility re-export shim that forwards AuthContext, AuthProvider, useAuth,…
    • auth-provider — auth-provider.tsx is a thin back-compatibility re-export shim that forwards AuthContext, AuthProvider, useAuth,…
  • email-verification-view — <EmailVerificationView> is the pure-UI surface that renders the four states of an email-verification flow — `verifyin…
    • email-verification-view — <EmailVerificationView> is the pure-UI surface that renders the four states of an email-verification flow — `verifyin…
  • forgot-password-form — <ForgotPasswordForm> is the pure-UI surface for requesting a password-reset email. It owns the email input, the Zod v…
    • forgot-password-form — <ForgotPasswordForm> is the pure-UI surface for requesting a password-reset email. It owns the email input, the Zod v…
  • login-form — <LoginForm> is a pure-UI sign-in form used by the Wave 3 <Login> page (and any custom consumer). It owns the render…
    • login-form — <LoginForm> is a pure-UI sign-in form used by the Wave 3 <Login> page (and any custom consumer). It owns the render…
  • permission-gate — <PermissionGate> is a declarative conditional renderer that consumes the Wave 1 usePermission() hook and decides wh…
    • permission-gate — <PermissionGate> is a declarative conditional renderer that consumes the Wave 1 usePermission() hook and decides wh…
  • register-form — <RegisterForm> is the pure-UI surface for account creation. It renders an identity grid (email + username + password…
    • register-form-fields — <RegisterFormFields> is an internal helper that owns the responsive identity-grid layout used by <RegisterForm>. It…
    • register-form — <RegisterForm> is the pure-UI surface for account creation. It renders an identity grid (email + username + password…
  • reset-password-form — <ResetPasswordForm> is the pure-UI surface for setting a new password after the user clicks a reset link. It owns thr…
    • reset-password-form — <ResetPasswordForm> is the pure-UI surface for setting a new password after the user clicks a reset link. It owns thr…
  • test-wrap — Internal test helper consumed only by the Wave 2 form .test.tsx files in src/components/<form>/. The helper wraps a…
• context — auth-context.tsx exposes the React Context surface for the auth flow. It defines AuthContext, the AuthProvider co…
  • auth-context — auth-context.tsx exposes the React Context surface for the auth flow. It defines AuthContext, the AuthProvider co…
• error-codes — error-codes.ts defines the stable error-code registry for @suaveplan/react-auth plus the ten typed ReactAuthError…
  • error-codes — error-codes.ts defines the stable error-code registry for @suaveplan/react-auth plus the ten typed ReactAuthError…
• use-auth-guard — useAuthGuard(options) is the imperative counterpart to the declarative <AuthGuard> component. It reads the current…
• use-permission — usePermission() exposes a bitwise permission-check API over the current user.roles bitmask. The package ships a clo…
• lib — better-auth-adapter.ts provides the response-narrowing bridge between better-auth/client (which returns a `BetterAu…
  • better-auth-adapter — better-auth-adapter.ts provides the response-narrowing bridge between better-auth/client (which returns a `BetterAu…
• observability — react-auth-metrics.ts builds the OTel instrument set for @suaveplan/react-auth. Instruments are constructed lazily…
  • react-auth-metrics — react-auth-metrics.ts builds the OTel instrument set for @suaveplan/react-auth. Instruments are constructed lazily…
• email-verification — <EmailVerificationPage> is the routing-aware adapter that wraps the Wave 2 <EmailVerificationView> for the `?token=…
  • email-verification — <EmailVerificationPage> is the routing-aware adapter that wraps the Wave 2 <EmailVerificationView> for the `?token=…
• forgot-password — <ForgotPasswordPage> is the routing-aware adapter that wraps the Wave 2 <ForgotPasswordForm> with the navigation an…
  • forgot-password — <ForgotPasswordPage> is the routing-aware adapter that wraps the Wave 2 <ForgotPasswordForm> with the navigation an…
• login — <LoginPage> is the routing-aware adapter that wraps the Wave 2 <LoginForm> with the navigation and auth-context wir…
  • login — <LoginPage> is the routing-aware adapter that wraps the Wave 2 <LoginForm> with the navigation and auth-context wir…
• profile — <ProfilePage> is the routing-aware profile-settings surface for an authenticated user. It renders three tabs — Profil…
  • profile-account-section — profile-account-section.tsx houses the delete-account tab renderer for <ProfilePage>. It is split out of `profile-s…
  • profile-sections — profile-sections.tsx houses the two read/write tab renderers for <ProfilePage>: <ProfileSection> (name + email up…
  • profile — <ProfilePage> is the routing-aware profile-settings surface for an authenticated user. It renders three tabs — Profil…
• register — <RegisterPage> is the routing-aware adapter that wraps the Wave 2 <RegisterForm> with the navigation and auth-conte…
  • register — <RegisterPage> is the routing-aware adapter that wraps the Wave 2 <RegisterForm> with the navigation and auth-conte…
• reset-password — <ResetPasswordPage> is the routing-aware adapter that wraps the Wave 2 <ResetPasswordForm> for the ?token=…-beari…
  • reset-password — <ResetPasswordPage> is the routing-aware adapter that wraps the Wave 2 <ResetPasswordForm> for the ?token=…-beari…
• cy-gb — cy-gb.ts ships the Welsh (Cymraeg, cy-GB) translation pack for the auth surface. The file conforms structurally to…
• en-gb — en-gb.ts ships the British-English string table consumed by the Wave 2 forms and Wave 3 page components. The file als…
• zh-cn — zh-cn.ts ships the Simplified-Chinese (zh-CN) translation pack for the auth surface. The file conforms structurally…

Install

bun add @suaveplan/react-auth

Peer requirements: react@^19, react-dom@^19, react-router-dom@^7.

Quick start

import {
    AuthProvider,
    AuthGuard,
    createAuthClient,
    useAuth,
} from "@suaveplan/react-auth";

const client = createAuthClient({
    baseURL: "https://auth.example.com",
    siteDomain: "tenant-a",
});

export function App({ children }: { children: React.ReactNode }) {
    return (
        <AuthProvider config={{ baseURL: "https://auth.example.com" }} client={client}>
            <AuthGuard requireAuth requireVerified fallback={<LoginRedirect />}>
                {children}
            </AuthGuard>
        </AuthProvider>
    );
}

function Profile() {
    const { user, signOut } = useAuth();
    return (
        <>
            <h1>{user?.email}</h1>
            <button onClick={() => signOut()}>Sign out</button>
        </>
    );
}

Modules

• src/client/auth-client.md — typed wrapper around better-auth/client, propagates x-site-domain.
• src/context/auth-context.md — AuthProvider + useAuth + 11 actions.
• src/components/auth-guard/auth-guard.md — declarative gate component.
• src/components/auth-provider/auth-provider.md — back-compat re-export of the context surface.
• src/hooks/use-auth-guard.md — imperative react-router-dom redirect counterpart.
• src/hooks/use-permission.md — bitwise permission check (16 flags).
• src/lib/better-auth-adapter.md — narrows better-auth response unions to internal shapes.
• src/error-codes/error-codes.md — REACT_AUTH_CODES registry + 10 typed error classes.
• src/observability/react-auth-metrics.md — counters + histogram under suaveplan.react-auth.
• src/translations/en-gb.md — British English locale pack + AuthTranslationPack shape.
• src/translations/cy-gb.md — Welsh locale pack.
• src/translations/zh-cn.md — Simplified Chinese locale pack.
• src/types/auth.types.md — User, Session, credential / response shapes.
• src/types/crud.types.md — multi-tenant CRUD shapes (Site, UserSettings, Friend, …).

Wave scope

This package is the Wave 1 core. The Wave 2 forms (LoginForm, RegisterForm, ForgotPasswordForm, ResetPasswordForm, EmailVerifyForm) and Wave 3 page components (Login, Register, ForgotPassword, ResetPassword, EmailVerify, Profile, PermissionGate) extend this core without changing it.

Observability

All instrumented call paths emit through metrics.getMeter("suaveplan.react-auth"). Counters: react_auth.sign_in.total, react_auth.sign_up.total, react_auth.sign_out.total, react_auth.guard.allow.total, react_auth.guard.deny.total. Histogram: react_auth.session_fetch.duration_ms.