WorkOS AuthKit for React Router
Decision Tree
1. Fetch README (BLOCKING)
2. Detect router mode
3. Follow README for that mode
4. Verify with checklist belowPhase 1: Fetch SDK Documentation (BLOCKING)
STOP - Do not write any code until this completes.
WebFetch: https://github.com/workos/authkit-react-router/blob/main/README.md
The README is the source of truth. If this skill conflicts with README, follow the README.
Phase 2: Detect Router Mode
| Mode | Detection Signal | Key Indicator |
|---|---|---|
| v7 Framework | react-router.config.ts exists | Routes in app/routes/ |
| v7 Data | createBrowserRouter in source | Loaders in route config |
| v7 Declarative | <BrowserRouter> component | Routes as JSX, no loaders |
| v6 | package.json version "6.x" | Similar to v7 Declarative |
Detection order:
- Check for
react-router.config.ts(Framework mode) - Grep for
createBrowserRouter(Data mode) - Check package.json version (v6 vs v7)
- Default to Declarative if v7 with
<BrowserRouter>
Phase 3: Follow README
Based on detected mode, apply the corresponding README section. The README contains current API signatures and code patterns.
Critical Distinctions
authLoader vs authkitLoader
| Function | Purpose | Where to use |
|---|---|---|
authLoader | OAuth callback handler | Callback route ONLY |
authkitLoader | Fetch user data in routes | Any route needing auth |
Common mistake: Using authkitLoader for callback route. Use authLoader().
Root Route Requirement
Auth loader MUST be on root route for child routes to access auth context.
Wrong: Auth loader only on /dashboard Right: Auth loader on / (root), children inherit context
Environment Variables
Required in .env or .env.local:
WORKOS_API_KEY- starts withsk_WORKOS_CLIENT_ID- starts withclient_WORKOS_REDIRECT_URI- full URL (e.g.,http://localhost:3000/auth/callback)WORKOS_COOKIE_PASSWORD- 32+ chars (server modes only)
Verification Checklist
After implementation, verify:
- SDK installed in node_modules (package name from README)
- Callback route path matches
WORKOS_REDIRECT_URIpath segment - Auth loader/provider on root route (not just child routes)
- Build succeeds:
npm run buildexits 0 - Correct mode pattern applied (loaders vs hooks)
Error Recovery
"loader is not a function"
Cause: Using loader pattern in Declarative/v6 mode Fix: Declarative/v6 modes use AuthKitProvider + useAuth hook, not loaders
Auth state not available in child routes
Cause: Auth loader missing from root route Fix: Add authkitLoader (or AuthKitProvider) to root route so children inherit context
useAuth returns undefined
Cause: Missing AuthKitProvider wrapper Fix: Wrap app with AuthKitProvider (required for Declarative/v6 modes)
Callback route 404
Cause: Route path mismatch with WORKOS_REDIRECT_URI Fix: Extract exact path from env var, create route at that path
"Module not found" for SDK
Cause: SDK not installed Fix: Install SDK, wait for completion, verify node_modules before writing imports