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
  │
  ├─► 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

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 Dashboard中的配置完全一致即可。

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"

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

）是否将

<App />

包裹在

<AuthKitProvider>

内部。

Callback redirect fails

回调重定向失败

Cause: URI mismatch

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

原因： URI不匹配

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