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

vite.config.ts

VITE_

import.meta.env.VITE_*

craco.config.js

REACT_APP_

process.env.REACT_APP_*

Key Clarification: No Callback Route

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

Required Environment Variables

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

WORKOS_API_KEY

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"

VITE_

REACT_APP_

Auth state lost on refresh

useAuth returns undefined

main.tsx

index.tsx

<App />

<AuthKitProvider>

Callback redirect fails