Library Overview
+react-auth owns three concerns and nothing else: session state, the
+authenticated HTTP client, and the screens that produce a session. It
+talks to an auth server over HTTP — it never issues, validates or decodes
+tokens itself.
+
🧭 What lives where
+| Concern | +Module | +Notes | +
|---|---|---|
| Session state | +contexts.tsx |
+AuthProvider, useAuth, AuthServerConfig |
+
| Authenticated HTTP client | +axios.ts |
+createApiClient, attachAuthInterceptors |
+
| Token persistence | +token.ts |
+tokenStore (localStorage, key "token") |
+
| Login / register screen | +AuthPage.tsx |
+AuthPage, AuthMode |
+
| Profile screens | +Profile*.tsx |
+controlled presentational components | +
| User model | +models.ts |
+AuthUser |
+
The package entry (index.ts) re-exports the public surface; nothing else in
+the app should import the internals directly.
+
🔄 Session lifecycle
+-
+
- Bootstrap —
AuthProviderseeds its token fromtokenStore.get().
+ - Resolve the user — whenever the token changes,
mePathis fetched and +currentUseris set (or cleared).
+ - Login —
login(username, password)posts tologinPath, stores +access_tokenthroughtokenStore, and takescurrentUserfrom the + responseuser.
+ - Register —
register(...)creates the account, then logs in.
+ - Request — every client built by
createApiClientattaches +Authorization: Bearer <token>fromtokenStore.
+ - Expiry — a
401clears the token and dispatches an +auth:unauthorizedwindow event;AuthProviderlistens, clears the + session, and invokes the optionalonUnauthorizedcallback.
+ - Logout — best-effort call to
logoutPath, then local state is always + cleared.
+
One source of truth
+tokenStore is the only place the token is written. Reading it from
+anywhere else will desynchronise the UI from the network layer.
+
🏗️ Endpoint contract
+AuthServerConfig is the complete wiring surface; every path resolves
+relative to serverUrl:
| Field | +Shape | +
|---|---|
loginPath |
+POST { username, password } → { access_token, user } |
+
registerPath |
+POST { username, password } to create an account |
+
logoutPath |
+called on logout; failures are ignored | +
mePath |
+returns the current AuthUser for a valid bearer token |
+
introspectPath |
+token introspection, available to callers that need it | +
AuthUser is intentionally permissive so it can be spread into application
+state without loss.
+
Split-screen login / register screen.
+A presentational page: it performs client-side validation (username >= 3 +chars, password >= 6 chars) and then calls the
+loginorregister+callback you pass in (typically theuseAuthactions). WhencurrentUser+becomes truthy it automatically callsonBack, so it can be rendered as a +route guard that redirects once authentication succeeds. The whole page is +controlled bymode, which letsonSwitchModetoggle between sign in and +sign up without unmounting.Props:
++
+
+
+
+
+
+
+
+
+mode-"login"or"register"; selects the form.onBack- called to leave the page (and automatically on success).onSwitchMode- called to toggle between login and register.login-(username, password) => Promise<void>fromuseAuth.register-(username, password) => Promise<void>fromuseAuth.loading- disables the submit button and shows a spinner.error- server error message to display.currentUser- when set, triggersonBack.