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.