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

Marker File	Build Tool	Env Prefix	Access Pattern
vite.config.ts	Vite	VITE_	import.meta.env.VITE_*
craco.config.js or none	CRA	REACT_APP_	process.env.REACT_APP_*

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.