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

{user?.email}

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