workos-authkit-react-router

Original：🇺🇸 English

Translated

Integrate WorkOS AuthKit with React Router applications. Supports v6 and v7 (Framework, Data, Declarative modes). Use when project uses react-router, react-router-dom, or mentions React Router authentication.

1installs

Sourceworkos/skills

Added on2026-02-11

NPX Install

npx skill4agent add workos/skills workos-authkit-react-router

SKILL.md Content

View Translation Comparison →

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