WorkOS AuthKit for React (SPA)

Decision Tree

START
  │
  ├─► Fetch README (BLOCKING)
  │   github.com/workos/authkit-react/blob/main/README.md
  │   README is source of truth. Stop if fetch fails.
  │
  ├─► Detect Build Tool
  │   ├─ vite.config.ts exists? → Vite
  │   └─ otherwise → Create React App
  │
  ├─► Set Env Var Prefix
  │   ├─ Vite → VITE_WORKOS_CLIENT_ID
  │   └─ CRA  → REACT_APP_WORKOS_CLIENT_ID
  │
  └─► Implement per README

Critical: Build Tool Detection

Wrong prefix = undefined values at runtime. This is the #1 integration failure.

Key Clarification: No Callback Route

The React SDK handles OAuth callbacks internally via AuthKitProvider.

• •No server-side callback route needed
• •SDK intercepts redirect URI client-side
• •Token exchange happens automatically

Just ensure redirect URI env var matches WorkOS Dashboard exactly.

Required Environment Variables

{PREFIX}WORKOS_CLIENT_ID=client_...
{PREFIX}WORKOS_REDIRECT_URI=http://localhost:5173/callback

No WORKOS_API_KEY needed. Client-side only SDK.

Verification Checklist

• • README fetched and read
• • Build tool detected correctly
• • Env var prefix matches build tool
• • .env or .env.local has required vars
• • No next dependency (wrong skill)
• • No react-router dependency (wrong skill)
• • AuthKitProvider wraps app root
• • pnpm build exits 0

Error Recovery

"clientId is required"

Cause: Env var inaccessible (wrong prefix)

Check: Does prefix match build tool? Vite needs VITE_, CRA needs REACT_APP_.

Auth state lost on refresh

Cause: Token persistence issue

Check: Browser dev tools → Application → Local Storage. SDK stores tokens here automatically.

useAuth returns undefined

Cause: Component outside provider tree

Check: Entry file (main.tsx or index.tsx) wraps <App /> in <AuthKitProvider>.

Callback redirect fails

Cause: URI mismatch

Check: Env var redirect URI exactly matches WorkOS Dashboard → Redirects configuration.