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 below

Phase 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

Detection order:

1. Check for react-router.config.ts (Framework mode)
2. Grep for createBrowserRouter (Data mode)
3. Check package.json version (v6 vs v7)
4. 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

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 with sk_
• WORKOS_CLIENT_ID – starts with client_
• 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_URI path segment
• Auth loader/provider on root route (not just child routes)
• Build succeeds: npm run build exits 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