127 lines
13 KiB
Markdown
127 lines
13 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## 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/<form>/`. The helper wraps a…
|
|
- [auth-guard](./src/components/auth-guard/auth-guard.md) — `<AuthGuard>` 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) — `<AuthGuard>` 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) — `<EmailVerificationView>` 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) — `<EmailVerificationView>` 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) — `<ForgotPasswordForm>` 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) — `<ForgotPasswordForm>` 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) — `<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](./src/components/login-form/login-form.md) — `<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](./src/components/permission-gate/permission-gate.md) — `<PermissionGate>` is a declarative conditional renderer that consumes the Wave 1 `usePermission()` hook and decides wh…
|
|
- [permission-gate](./src/components/permission-gate/permission-gate.md) — `<PermissionGate>` is a declarative conditional renderer that consumes the Wave 1 `usePermission()` hook and decides wh…
|
|
- [register-form](./src/components/register-form/register-form.md) — `<RegisterForm>` 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) — `<RegisterFormFields>` is an internal helper that owns the responsive identity-grid layout used by `<RegisterForm>`. It…
|
|
- [register-form](./src/components/register-form/register-form.md) — `<RegisterForm>` 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) — `<ResetPasswordForm>` 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) — `<ResetPasswordForm>` 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/<form>/`. 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 `<AuthGuard>` 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) — `<EmailVerificationPage>` is the routing-aware adapter that wraps the Wave 2 `<EmailVerificationView>` for the `?token=…
|
|
- [email-verification](./src/pages/email-verification/email-verification.md) — `<EmailVerificationPage>` is the routing-aware adapter that wraps the Wave 2 `<EmailVerificationView>` for the `?token=…
|
|
- [forgot-password](./src/pages/forgot-password/forgot-password.md) — `<ForgotPasswordPage>` is the routing-aware adapter that wraps the Wave 2 `<ForgotPasswordForm>` with the navigation an…
|
|
- [forgot-password](./src/pages/forgot-password/forgot-password.md) — `<ForgotPasswordPage>` is the routing-aware adapter that wraps the Wave 2 `<ForgotPasswordForm>` with the navigation an…
|
|
- [login](./src/pages/login/login.md) — `<LoginPage>` is the routing-aware adapter that wraps the Wave 2 `<LoginForm>` with the navigation and auth-context wir…
|
|
- [login](./src/pages/login/login.md) — `<LoginPage>` is the routing-aware adapter that wraps the Wave 2 `<LoginForm>` with the navigation and auth-context wir…
|
|
- [profile](./src/pages/profile/profile.md) — `<ProfilePage>` 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 `<ProfilePage>`. 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 `<ProfilePage>`: `<ProfileSection>` (name + email up…
|
|
- [profile](./src/pages/profile/profile.md) — `<ProfilePage>` is the routing-aware profile-settings surface for an authenticated user. It renders three tabs — Profil…
|
|
- [register](./src/pages/register/register.md) — `<RegisterPage>` is the routing-aware adapter that wraps the Wave 2 `<RegisterForm>` with the navigation and auth-conte…
|
|
- [register](./src/pages/register/register.md) — `<RegisterPage>` is the routing-aware adapter that wraps the Wave 2 `<RegisterForm>` with the navigation and auth-conte…
|
|
- [reset-password](./src/pages/reset-password/reset-password.md) — `<ResetPasswordPage>` is the routing-aware adapter that wraps the Wave 2 `<ResetPasswordForm>` for the `?token=…`-beari…
|
|
- [reset-password](./src/pages/reset-password/reset-password.md) — `<ResetPasswordPage>` is the routing-aware adapter that wraps the Wave 2 `<ResetPasswordForm>` 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…
|
|
<!-- end:auto-docs -->
|
|
|
|
## 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 (
|
|
<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`](./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`.
|
|
|