workos-authkit-base

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WorkOS AuthKit Base Template

WorkOS AuthKit 基础模板

First Action: Fetch README

第一步：获取README

Before any implementation, fetch the framework-specific README:

WebFetch: {sdk-package-name} README from npmjs.com or GitHub

README is the source of truth for: install commands, imports, API usage, code patterns.

在进行任何实现之前，请获取对应框架的README：

WebFetch: {sdk-package-name} README from npmjs.com or GitHub

README是以下内容的权威来源：安装命令、导入方式、API使用方法、代码模式。

Task Structure (Required)

任务结构（必填）

Phase	Task	Blocked By	Purpose
1	preflight	-	Verify env vars, detect framework
2	install	preflight	Install SDK package
3	callback	install	Create OAuth callback route
4	provider	install	Setup auth context/middleware
5	ui	callback, provider	Add sign-in/out UI
6	verify	ui	Build confirmation

阶段	任务	依赖前置任务	目的
1	预检	-	验证环境变量，检测框架
2	安装	预检	安装SDK包
3	回调路由	安装	创建OAuth回调路由
4	提供者/中间件	安装	设置认证上下文/中间件
5	用户界面	回调路由、提供者/中间件	添加登录/登出UI
6	验证	用户界面	构建确认环节

Decision Trees

决策树

Package Manager Detection

包管理器检测

pnpm-lock.yaml? → pnpm
yarn.lock? → yarn
bun.lockb? → bun
else → npm

pnpm-lock.yaml? → pnpm
yarn.lock? → yarn
bun.lockb? → bun
else → npm

Provider vs Middleware

提供者 vs 中间件

Client-side framework? → AuthKitProvider wraps app
Server-side framework? → Middleware handles sessions
Hybrid (Next.js)? → Both may be needed

客户端框架？→ 使用AuthKitProvider包裹应用
服务端框架？→ 使用中间件处理会话
混合框架（如Next.js）？→ 两者可能都需要

Callback Route Location

回调路由位置

Extract path from

WORKOS_REDIRECT_URI

→ create route at that exact path.

从

WORKOS_REDIRECT_URI

中提取路径 → 在该精确路径下创建路由。

Environment Variables

环境变量

Variable	Purpose	When Required
`WORKOS_API_KEY`	Server authentication	Server SDKs
`WORKOS_CLIENT_ID`	Client identification	All SDKs
`WORKOS_REDIRECT_URI`	OAuth callback URL	Server SDKs
`WORKOS_COOKIE_PASSWORD`	Session encryption (32+ chars)	Server SDKs

Note: Some frameworks use prefixed variants (e.g.,

NEXT_PUBLIC_*

). Check README.

变量名称	用途	必填场景
`WORKOS_API_KEY`	服务端认证	服务端SDK
`WORKOS_CLIENT_ID`	客户端标识	所有SDK
`WORKOS_REDIRECT_URI`	OAuth回调URL	服务端SDK
`WORKOS_COOKIE_PASSWORD`	会话加密（需32个字符以上）	服务端SDK

注意：部分框架使用带前缀的变量变体（如

NEXT_PUBLIC_*

）。请查看README确认。

Verification Checklists

验证检查清单

After Install

安装完成后

SDK package installed in node_modules
No install errors in output

SDK包已安装在node_modules中
安装输出中无错误信息

After Callback Route

回调路由创建后

Route file exists at path matching
```
WORKOS_REDIRECT_URI
```
Imports SDK callback handler (not custom OAuth)

路由文件存在于与
```
WORKOS_REDIRECT_URI
```
匹配的路径下
导入了SDK的回调处理程序（而非自定义OAuth实现）

After Provider/Middleware

提供者/中间件设置后

Provider wraps entire app (client-side)
Middleware configured in correct location (server-side)

提供者已包裹整个应用（客户端）
中间件已配置在正确位置（服务端）

After UI

用户界面完成后

Home page shows conditional auth state
Uses SDK functions for sign-in/out URLs

主页显示条件化的认证状态
使用SDK函数生成登录/登出URL

Final Verification

最终验证

Build completes with exit code 0
No import resolution errors

构建完成且退出码为0
无导入解析错误

Error Recovery

错误排查

Module not found

模块未找到

Verify install completed successfully
Verify SDK exists in node_modules
Re-run install if missing

确认安装已成功完成
确认SDK存在于node_modules中
若缺失则重新运行安装命令

Build import errors

构建导入错误

Delete
```
node_modules
```
, reinstall
Verify package.json has SDK dependency

删除
```
node_modules
```
，重新安装
确认package.json中包含SDK依赖

Invalid redirect URI

重定向URI无效

Compare route path to
```
WORKOS_REDIRECT_URI
```
Paths must match exactly

对比路由路径与
```
WORKOS_REDIRECT_URI
```
路径必须完全匹配

Cookie password error

Cookie密码错误

Verify
```
WORKOS_COOKIE_PASSWORD
```
is 32+ characters
Generate new:
```
openssl rand -base64 32
```

确认
```
WORKOS_COOKIE_PASSWORD
```
长度为32个字符以上
生成新密码：
```
openssl rand -base64 32
```

Auth state not persisting

认证状态未持久化

Verify provider wraps entire app
Check middleware is in correct location

确认提供者已包裹整个应用
检查中间件是否位于正确位置

Critical Rules

关键规则

Install SDK before writing imports - never create import statements for uninstalled packages
Use SDK functions - never construct OAuth URLs manually
Follow README patterns - SDK APIs change between versions
Extract callback path from env - don't hardcode
```
/auth/callback
```

先安装SDK再编写导入语句 - 切勿为未安装的包创建导入语句
使用SDK函数 - 切勿手动构建OAuth URL
遵循README中的代码模式 - SDK API会随版本更新而变化
从环境变量中提取回调路径 - 不要硬编码
```
/auth/callback
```