workos-authkit-tanstack-start

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WorkOS AuthKit for TanStack Start

适用于TanStack Start的WorkOS AuthKit

Decision Tree

决策树

1. Fetch README (BLOCKING)
   ├── Extract package name from install command
   └── README is source of truth for ALL code patterns

2. Detect directory structure
   ├── src/ (TanStack Start v1.132+, default)
   └── app/ (legacy vinxi-based projects)

3. Follow README install/setup exactly
   └── Do not invent commands or patterns

1. 获取README（阻塞步骤）
   ├── 从安装命令中提取包名
   └── README是所有代码模式的唯一可信来源

2. 检测目录结构
   ├── src/（TanStack Start v1.132+，默认结构）
   └── app/（基于vinxi的旧版项目）

3. 严格遵循README中的安装/设置步骤
   └── 请勿自行编写命令或模式

Fetch SDK Documentation (BLOCKING)

获取SDK文档（阻塞步骤）

STOP - Do not proceed until complete.

WebFetch:

https://github.com/workos/authkit-tanstack-start/blob/main/README.md

From README, extract:

Package name:
```
@workos/authkit-tanstack-react-start
```
Use that exact name for all imports

README overrides this skill if conflict.

停止操作 - 完成此步骤前请勿继续。

网络获取地址：

https://github.com/workos/authkit-tanstack-start/blob/main/README.md

从README中提取：

包名：
```
@workos/authkit-tanstack-react-start
```
所有导入语句必须使用此精确包名

若存在冲突，README内容优先级高于本技能文档。

Pre-Flight Checklist

预检查清单

README fetched and package name extracted
```
@tanstack/start
```
or
```
@tanstack/react-start
```
in package.json
Identify directory structure:
```
src/
```
(modern) or
```
app/
```
(legacy)
Environment variables set (see below)

已获取README并提取包名
package.json中包含
```
@tanstack/start
```
或
```
@tanstack/react-start
```
已识别目录结构：
```
src/
```
（现代版）或
```
app/
```
（旧版）
已设置环境变量（见下文）

Directory Structure Detection

目录结构检测

Modern TanStack Start (v1.132+) uses

src/

src/
├── start.ts              # Middleware config (CRITICAL)
├── router.tsx            # Router setup
├── routes/
│   ├── __root.tsx        # Root layout
│   ├── api.auth.callback.tsx  # OAuth callback (flat route)
│   └── ...

Legacy (vinxi-based) uses

app/

app/
├── start.ts or router.tsx
├── routes/
│   └── api/auth/callback.tsx  # OAuth callback (nested route)

Detection:

bash

ls src/routes 2>/dev/null && echo "Modern (src/)" || echo "Legacy (app/)"

**现代版TanStack Start（v1.132+）**使用

src/

src/
├── start.ts              # 中间件配置（关键文件）
├── router.tsx            # 路由设置
├── routes/
│   ├── __root.tsx        # 根布局
│   ├── api.auth.callback.tsx  # OAuth回调（扁平路由）
│   └── ...

**旧版（基于vinxi）**使用

app/

app/
├── start.ts 或 router.tsx
├── routes/
│   └── api/auth/callback.tsx  # OAuth回调（嵌套路由）

检测命令：

bash

ls src/routes 2>/dev/null && echo "Modern (src/)" || echo "Legacy (app/)"

Environment Variables

环境变量

Variable	Format	Required
`WORKOS_API_KEY`	`sk_...`	Yes
`WORKOS_CLIENT_ID`	`client_...`	Yes
`WORKOS_REDIRECT_URI`	Full URL	Yes
`WORKOS_COOKIE_PASSWORD`	32+ chars	Yes

Generate password if missing:

openssl rand -base64 32

Default redirect URI:

http://localhost:3000/api/auth/callback

变量名	格式	是否必填
`WORKOS_API_KEY`	`sk_...`	是
`WORKOS_CLIENT_ID`	`client_...`	是
`WORKOS_REDIRECT_URI`	完整URL	是
`WORKOS_COOKIE_PASSWORD`	32字符以上	是

如果缺少密码，生成方式：

openssl rand -base64 32

默认重定向URI：

http://localhost:3000/api/auth/callback

Middleware Configuration (CRITICAL)

中间件配置（关键步骤）

authkitMiddleware MUST be configured or auth will fail silently.

Create or update

src/start.ts

(or

app/start.ts

for legacy):

typescript

import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';

export default {
  requestMiddleware: [authkitMiddleware()],
};

Alternative pattern with createStart:

typescript

import { createStart } from '@tanstack/react-start';
import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';

export default createStart({
  requestMiddleware: [authkitMiddleware()],
});

必须配置authkitMiddleware，否则认证会静默失败。

创建或更新

src/start.ts

（旧版项目为

app/start.ts

）：

typescript

import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';

export default {
  requestMiddleware: [authkitMiddleware()],
};

另一种使用createStart的写法：

typescript

import { createStart } from '@tanstack/react-start';
import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';

export default createStart({
  requestMiddleware: [authkitMiddleware()],
});

Verification Checklist

验证清单

authkitMiddleware

imported from

@workos/authkit-tanstack-react-start

Middleware in
```
requestMiddleware
```
array
File exports the config (default export or named
```
startInstance
```
)

Verify:

grep -r "authkitMiddleware" src/ app/ 2>/dev/null

已从

@workos/authkit-tanstack-react-start

导入

authkitMiddleware

中间件已加入
```
requestMiddleware
```
数组
文件已导出配置（默认导出或命名为
```
startInstance
```
）

验证命令：

grep -r "authkitMiddleware" src/ app/ 2>/dev/null

Callback Route (CRITICAL)

回调路由（关键步骤）

Path must match

WORKOS_REDIRECT_URI

. For

/api/auth/callback

Modern (flat routes):

src/routes/api.auth.callback.tsx

Legacy (nested routes):

app/routes/api/auth/callback.tsx

typescript

import { createFileRoute } from '@tanstack/react-router';
import { handleCallbackRoute } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/api/auth/callback')({
  server: {
    handlers: {
      GET: handleCallbackRoute(),
    },
  },
});

Key points:

Use
```
handleCallbackRoute()
```
- do not write custom OAuth logic
Route path string must match the URI path exactly
This is a server-only route (no component needed)

路径必须与

WORKOS_REDIRECT_URI

匹配。对于

/api/auth/callback

：

现代版（扁平路由）：

src/routes/api.auth.callback.tsx

旧版（嵌套路由）：

app/routes/api/auth/callback.tsx

typescript

import { createFileRoute } from '@tanstack/react-router';
import { handleCallbackRoute } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/api/auth/callback')({
  server: {
    handlers: {
      GET: handleCallbackRoute(),
    },
  },
});

关键点：

使用
```
handleCallbackRoute()
```
- 请勿编写自定义OAuth逻辑
```
createFileRoute()
```
中的路由路径字符串必须与URI路径完全匹配
这是仅服务端路由（无需组件）

Protected Routes

受保护的路由

Use

getAuth()

in route loaders to check authentication:

typescript

import { createFileRoute, redirect } from '@tanstack/react-router';
import { getAuth, getSignInUrl } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/dashboard')({
  loader: async () => {
    const { user } = await getAuth();
    if (!user) {
      const signInUrl = await getSignInUrl();
      throw redirect({ href: signInUrl });
    }
    return { user };
  },
  component: Dashboard,
});

在路由加载器中使用

getAuth()

检查认证状态：

typescript

import { createFileRoute, redirect } from '@tanstack/react-router';
import { getAuth, getSignInUrl } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/dashboard')({
  loader: async () => {
    const { user } = await getAuth();
    if (!user) {
      const signInUrl = await getSignInUrl();
      throw redirect({ href: signInUrl });
    }
    return { user };
  },
  component: Dashboard,
});

Sign Out Route

退出登录路由

typescript

import { createFileRoute, redirect } from '@tanstack/react-router';
import { signOut } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/signout')({
  loader: async () => {
    await signOut();
    throw redirect({ href: '/' });
  },
});

typescript

import { createFileRoute, redirect } from '@tanstack/react-router';
import { signOut } from '@workos/authkit-tanstack-react-start';

export const Route = createFileRoute('/signout')({
  loader: async () => {
    await signOut();
    throw redirect({ href: '/' });
  },
});

Client-Side Hooks (Optional)

客户端Hook（可选）

Only needed if you want reactive auth state in components.

1. Add AuthKitProvider to root:

typescript

// src/routes/__root.tsx
import { AuthKitProvider } from '@workos/authkit-tanstack-react-start/client';

function RootComponent() {
  return (
    <AuthKitProvider>
      <Outlet />
    </AuthKitProvider>
  );
}

2. Use hooks in components:

typescript

import { useAuth } from '@workos/authkit-tanstack-react-start/client';

function Profile() {
  const { user, isLoading } = useAuth();
  // ...
}

Note: Server-side

getAuth()

is preferred for most use cases.

仅在需要在组件中使用响应式认证状态时需要。

1. 为根布局添加AuthKitProvider：

typescript

// src/routes/__root.tsx
import { AuthKitProvider } from '@workos/authkit-tanstack-react-start/client';

function RootComponent() {
  return (
    <AuthKitProvider>
      <Outlet />
    </AuthKitProvider>
  );
}

2. 在组件中使用Hook：

typescript

import { useAuth } from '@workos/authkit-tanstack-react-start/client';

function Profile() {
  const { user, isLoading } = useAuth();
  // ...
}

注意： 大多数场景下优先使用服务端的

getAuth()

。

Error Recovery

错误排查

"AuthKit middleware is not configured"

Cause:

authkitMiddleware()

not in start.ts Fix: Create/update

src/start.ts

with middleware config Verify:

grep -r "authkitMiddleware" src/

原因：

start.ts

中未配置

authkitMiddleware()

解决方法： 创建或更新

src/start.ts

并添加中间件配置 验证：

grep -r "authkitMiddleware" src/

"Module not found" for SDK

Cause: Wrong package name or not installed Fix:

pnpm add @workos/authkit-tanstack-react-start

Verify:

ls node_modules/@workos/authkit-tanstack-react-start

原因： 包名错误或未安装SDK 解决方法： 执行

pnpm add @workos/authkit-tanstack-react-start

验证：

ls node_modules/@workos/authkit-tanstack-react-start

Callback 404

回调路由404

Cause: Route file path doesn't match WORKOS_REDIRECT_URI Fix:

URI

/api/auth/callback

→ file

src/routes/api.auth.callback.tsx

(flat) or

app/routes/api/auth/callback.tsx

(nested)

Route path string in
```
createFileRoute()
```
must match exactly

原因： 路由文件路径与WORKOS_REDIRECT_URI不匹配 解决方法：

URI为

/api/auth/callback

→ 对应文件为

src/routes/api.auth.callback.tsx

（扁平路由）或

app/routes/api/auth/callback.tsx

（嵌套路由）

```
createFileRoute()
```
中的路由路径字符串必须完全匹配

getAuth returns undefined user

getAuth返回undefined用户

Cause: Middleware not configured or not running Fix: Ensure

authkitMiddleware()

is in start.ts requestMiddleware array

原因： 中间件未配置或未运行 解决方法： 确保

authkitMiddleware()

已加入start.ts的requestMiddleware数组

"Cookie password too short"

Cause: WORKOS_COOKIE_PASSWORD < 32 chars Fix:

openssl rand -base64 32

, update .env

原因： WORKOS_COOKIE_PASSWORD长度不足32字符 解决方法： 执行

openssl rand -base64 32

生成新密码，更新.env文件

Build fails with route type errors

构建时出现路由类型错误

Cause: Route tree not regenerated after adding routes Fix:

pnpm dev

to regenerate

routeTree.gen.ts

原因： 添加路由后未重新生成路由树 解决方法： 执行

pnpm dev

重新生成

routeTree.gen.ts

SDK Exports Reference

SDK导出项参考

Server (main export):

```
authkitMiddleware()
```
- Request middleware
```
handleCallbackRoute()
```
- OAuth callback handler
```
getAuth()
```
- Get current session
```
signOut()
```
- Sign out user
```
getSignInUrl()
```
/
```
getSignUpUrl()
```
- Auth URLs
```
switchToOrganization()
```
- Change org context

Client (
/client
subpath):

```
AuthKitProvider
```
- Context provider
```
useAuth()
```
- Auth state hook
```
useAccessToken()
```
- Token management

服务端（主导出）：

```
authkitMiddleware()
```
- 请求中间件
```
handleCallbackRoute()
```
- OAuth回调处理器
```
getAuth()
```
- 获取当前会话
```
signOut()
```
- 退出用户登录
```
getSignInUrl()
```
/
```
getSignUpUrl()
```
- 认证URL
```
switchToOrganization()
```
- 切换组织上下文

客户端（
/client
子路径）：

```
AuthKitProvider
```
- 上下文提供者
```
useAuth()
```
- 认证状态Hook
```
useAccessToken()
```
- Token管理Hook