@realchemistry/auth-guard-react

React companion to @realchemistry/auth-guard. The chassis does the authentication; this package only reads the result and renders a standard sign-in pill.

When to use

Use this package if and only if your RC app is React-based and you want the standard user-pill UI without re-deriving fetch('/auth/me'), loading states, and sign-out plumbing per app. Non-React apps (Streamlit, Flask, Express templates) should keep reading the three x-rc-user-* headers directly server-side.

This package does not authenticate anyone. The auth-guard chassis still does all of that. This package only reads /auth/me and renders the result.

Install

pnpm add @realchemistry/auth-guard-react

Requires that @realchemistry/auth-guard is already wired into the project (the auth-guard serve chassis is what serves /auth/me).

Use

import { AuthProvider, UserMenu, useAuth } from "@realchemistry/auth-guard-react";

export function App() {
  return (
    <AuthProvider>
      <header>
        <h1>My RC App</h1>
        <UserMenu />
      </header>
      <Main />
    </AuthProvider>
  );
}

function Main() {
  const { email, loading } = useAuth();
  if (loading) return <p>Loading…</p>;
  return <p>Welcome, {email}</p>;
}

API

<AuthProvider>

Holds the auth context. Fetches /auth/me once on mount; exposes the result via context.

Props:

| Prop | Type | Default | Notes | |---|---|---|---| | meUrl | string | "/auth/me" | Override if the chassis serves /auth/me at a non-default path. | | initial | { email, sub, emailVerified } | — | Skip the first fetch if identity is pre-injected (SSR). | | children | ReactNode | — | Your app. |

useAuth()

const { email, sub, emailVerified, loading, error, refetch } = useAuth();

Throws if called outside <AuthProvider>.

<UserMenu/>

Renders a pill with the user's email and a "Sign out" link. While loading, renders a neutral skeleton. If unauthenticated, renders a "Sign in" link.

Props (all optional):

| Prop | Type | Default | |---|---|---| | loginUrl | string | "/auth/login" | | logoutUrl | string | "/auth/logout" | | next | string | current pathname | | renderLabel | (state) => string | ({email}) => email | | className | string | — | | style | CSSProperties | — | | loadingFallback | ReactNode | built-in skeleton |

Style via CSS variables on any parent:

:root {
  --rc-auth-bg: #f4f4f5;
  --rc-auth-fg: #18181b;
  --rc-auth-border: #e4e4e7;
  --rc-auth-link: #2563eb;
  --rc-auth-skeleton-bg: #e4e4e7;
  --rc-auth-fontsize: 0.875rem;
}

For richer customization, skip <UserMenu/> and build your own with useAuth().

What this package does not do

• It does not authenticate. The chassis does.
• It does not redirect. It renders a sign-in link; the chassis handles the OAuth round-trip when the link is clicked.
• It does not poll. It fetches /auth/me once on mount. Call refetch() if you need to re-check (e.g. after a sign-out the chassis just handled).
• It does not gate route access (no <RequireAuth>). The chassis bounces unauthenticated requests server-side before React renders, so a client-side route gate would be dead code in most cases.