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

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 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