AgentSkillsCN

workos-authkit-react-router

将 WorkOS AuthKit 与 React Router 应用程序集成。支持 v6 和 v7（Framework、Data、Declarative 模式）。当项目使用 react-router、react-router-dom，或提及 React Router 认证时，此技能将助您一臂之力。

SKILL.md
--- frontmatter
name: workos-authkit-react-router
description: 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.

WorkOS AuthKit for React Router

Decision Tree

code
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

ModeDetection SignalKey Indicator
v7 Frameworkreact-router.config.ts existsRoutes in app/routes/
v7 DatacreateBrowserRouter in sourceLoaders in route config
v7 Declarative<BrowserRouter> componentRoutes as JSX, no loaders
v6package.json version "6.x"Similar to v7 Declarative

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

FunctionPurposeWhere to use
authLoaderOAuth callback handlerCallback route ONLY
authkitLoaderFetch user data in routesAny 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