workos-authkit-react-router

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WorkOS AuthKit for React Router

适用于React Router的WorkOS AuthKit

Decision Tree

决策流程

1. Fetch README (BLOCKING)
2. Detect router mode
3. Follow README for that mode
4. Verify with checklist below

1. 获取README（阻塞操作）
2. 检测路由模式
3. 遵循对应模式的README指引
4. 使用下方的检查清单进行验证

Phase 1: Fetch SDK Documentation (BLOCKING)

阶段1：获取SDK文档（阻塞操作）

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.

暂停 - 完成此步骤前请勿编写任何代码。

WebFetch:

https://github.com/workos/authkit-react-router/blob/main/README.md

README是权威来源。如果本技能内容与README冲突，请以README为准。

Phase 2: Detect Router Mode

阶段2：检测路由模式

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

模式	检测信号	关键指标
v7 Framework	存在 `react-router.config.ts` 文件	路由位于 `app/routes/` 目录
v7 Data	源码中存在 `createBrowserRouter`	路由配置中包含Loaders
v7 Declarative	使用 `<BrowserRouter>` 组件	路由以JSX形式编写，无loaders
v6	package.json中版本为 `"6.x"`	与v7 Declarative模式类似

检测顺序：

检查是否存在
```
react-router.config.ts
```
（Framework模式）
搜索
```
createBrowserRouter
```
（Data模式）
查看package.json中的版本（v6 vs v7）
若为v7且使用
```
<BrowserRouter>
```
，默认归为Declarative模式

Phase 3: Follow README

阶段3：遵循README指引

Based on detected mode, apply the corresponding README section. The README contains current API signatures and code patterns.

根据检测到的模式，应用README中对应的章节内容。README包含最新的API签名和代码模式。

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

函数	用途	使用场景
`authLoader`	OAuth回调处理程序	仅用于回调路由
`authkitLoader`	在路由中获取用户数据	任何需要身份验证的路由

常见错误： 在回调路由中使用

authkitLoader

。请使用

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

身份验证loader必须配置在根路由上，以便子路由能够访问身份验证上下文。

错误做法： 仅在

/dashboard

路由上配置身份验证loader 正确做法： 在

（根路由）上配置身份验证loader，子路由继承上下文

Environment Variables

环境变量

Required in

.env

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

需在

.env

或

.env.local

中配置：

```
WORKOS_API_KEY
```
- 以
```
sk_
```
开头
```
WORKOS_CLIENT_ID
```
- 以
```
client_
```
开头

WORKOS_REDIRECT_URI

- 完整URL（例如：

http://localhost:3000/auth/callback

）

```
WORKOS_COOKIE_PASSWORD
```
- 32个字符以上（仅服务器模式需要）

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)

完成集成后，请验证以下内容：

SDK已安装在node_modules中（包名以README为准）
回调路由路径与
```
WORKOS_REDIRECT_URI
```
的路径段匹配
身份验证loader/提供者配置在根路由上（而非仅子路由）
构建成功：
```
npm run build
```
执行后返回0
应用了正确的模式（loaders vs 钩子）

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

原因： 在Declarative/v6模式中使用了loader模式 解决方法： Declarative/v6模式使用

AuthKitProvider

useAuth

钩子，而非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

原因： 根路由缺少身份验证loader 解决方法： 为根路由添加

authkitLoader

（或

AuthKitProvider

），使子路由能够继承上下文

useAuth returns undefined

useAuth返回undefined

Cause: Missing

AuthKitProvider

wrapper Fix: Wrap app with

AuthKitProvider

(required for Declarative/v6 modes)

原因： 缺少

AuthKitProvider

包裹 解决方法： 使用

AuthKitProvider

包裹应用（Declarative/v6模式必需）

Callback route 404

回调路由返回404

Cause: Route path mismatch with

WORKOS_REDIRECT_URI

Fix: Extract exact path from env var, create route at that path

原因： 路由路径与

WORKOS_REDIRECT_URI

不匹配 解决方法： 从环境变量中提取精确路径，创建对应路由

"Module not found" for SDK

SDK提示“Module not found”

Cause: SDK not installed Fix: Install SDK, wait for completion, verify

node_modules

before writing imports

原因： 未安装SDK 解决方法： 安装SDK，等待安装完成，编写导入语句前确认

node_modules

中存在该SDK