workos-authkit-react

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WorkOS AuthKit for React (SPA)

适用于React（SPA）的WorkOS AuthKit

Decision Tree

决策树

START
  │
  ├─► Fetch README (BLOCKING)
  │   github.com/workos/authkit-react/blob/main/README.md
  │   README is source of truth. Stop if fetch fails.
  │
  ├─► Detect Build Tool
  │   ├─ vite.config.ts exists? → Vite
  │   └─ otherwise → Create React App
  │
  ├─► Set Env Var Prefix
  │   ├─ Vite → VITE_WORKOS_CLIENT_ID
  │   └─ CRA  → REACT_APP_WORKOS_CLIENT_ID
  │
  └─► Implement per README

START
  │
  ├─► 获取README（阻塞操作）
  │   github.com/workos/authkit-react/blob/main/README.md
  │   README为权威来源，若获取失败则终止。
  │
  ├─► 检测构建工具
  │   ├─ 是否存在vite.config.ts？→ Vite
  │   └─ 否则 → Create React App
  │
  ├─► 设置环境变量前缀
  │   ├─ Vite → VITE_WORKOS_CLIENT_ID
  │   └─ CRA  → REACT_APP_WORKOS_CLIENT_ID
  │
  └─► 按照README文档实现

Critical: Build Tool Detection

重点：构建工具检测

Marker File	Build Tool	Env Prefix	Access Pattern
`vite.config.ts`	Vite	`VITE_`	`import.meta.env.VITE_*`
`craco.config.js` or none	CRA	`REACT_APP_`	`process.env.REACT_APP_*`

Wrong prefix = undefined values at runtime. This is the #1 integration failure.

标记文件	构建工具	环境变量前缀	访问方式
`vite.config.ts`	Vite	`VITE_`	`import.meta.env.VITE_*`
`craco.config.js` 或无	CRA	`REACT_APP_`	`process.env.REACT_APP_*`

错误的前缀会导致运行时变量值为undefined，这是集成失败的首要原因。

Key Clarification: No Callback Route

关键说明：无需回调路由

The React SDK handles OAuth callbacks internally via AuthKitProvider.

No server-side callback route needed
SDK intercepts redirect URI client-side
Token exchange happens automatically

Just ensure redirect URI env var matches WorkOS Dashboard exactly.

React SDK通过AuthKitProvider内部处理OAuth回调。

无需服务器端回调路由
SDK在客户端拦截重定向URI
令牌交换自动完成

只需确保重定向URI环境变量与WorkOS控制台中的设置完全一致。

Required Environment Variables

必需的环境变量

{PREFIX}WORKOS_CLIENT_ID=client_...
{PREFIX}WORKOS_REDIRECT_URI=http://localhost:5173/callback

WORKOS_API_KEY

needed. Client-side only SDK.

{PREFIX}WORKOS_CLIENT_ID=client_...
{PREFIX}WORKOS_REDIRECT_URI=http://localhost:5173/callback

无需

WORKOS_API_KEY

，这是纯客户端SDK。

Verification Checklist

验证清单

README fetched and read
Build tool detected correctly
Env var prefix matches build tool
```
.env
```
or
```
.env.local
```
has required vars
No
```
next
```
dependency (wrong skill)
No
```
react-router
```
dependency (wrong skill)
AuthKitProvider wraps app root
```
pnpm build
```
exits 0

已获取并阅读README
已正确检测构建工具
环境变量前缀与构建工具匹配
```
.env
```
或
```
.env.local
```
文件包含所需变量
没有
```
next
```
依赖（使用了错误的技能包）
没有
```
react-router
```
依赖（使用了错误的技能包）
AuthKitProvider包裹了应用根组件
```
pnpm build
```
执行成功（退出码0）

Error Recovery

错误排查

"clientId is required"

"clientId 是必需的"

Cause: Env var inaccessible (wrong prefix)

Check: Does prefix match build tool? Vite needs

VITE_

, CRA needs

REACT_APP_

原因： 环境变量无法访问（前缀错误）

检查：环境变量前缀是否与构建工具匹配？Vite需要

VITE_

前缀，CRA需要

REACT_APP_

前缀。

Auth state lost on refresh

刷新后认证状态丢失

Cause: Token persistence issue

Check: Browser dev tools → Application → Local Storage. SDK stores tokens here automatically.

原因： 令牌持久化问题

检查：浏览器开发者工具 → 应用 → 本地存储。SDK会自动在此处存储令牌。

useAuth returns undefined

useAuth 返回 undefined

Cause: Component outside provider tree

Check: Entry file (

main.tsx

index.tsx

) wraps

<App />

<AuthKitProvider>

原因： 组件位于Provider树之外

检查：入口文件（

main.tsx

或

index.tsx

）是否使用

<AuthKitProvider>

包裹了

<App />

。

Callback redirect fails

回调重定向失败

Cause: URI mismatch

Check: Env var redirect URI exactly matches WorkOS Dashboard → Redirects configuration.

原因： URI不匹配

检查：环境变量中的重定向URI是否与WorkOS控制台 → 重定向配置完全一致。