workos-authkit-tanstack-start

用途

该技能用于把 WorkOS AuthKit 集成到 TanStack Start 应用中。适用条件：项目使用 TanStack Start、@tanstack/start 或 @tanstack/react-start，技术栈为带服务端函数的全栈 TypeScript。

主要能力

获取 SDK 文档：先抓取官方 README（https://raw.githubusercontent.com/workos/authkit-tanstack-start/main/README.md），并以其作为所有代码模式的准绳；README 与技能内容冲突时以 README 为准。安装包名称为 @workos/authkit-tanstack-react-start，所有导入均使用该名称。
目录结构识别：现代 TanStack Start（v1.132+）使用 src/；旧版 vinxi 项目使用 app/。检测命令：ls src/routes 2>/dev/null && echo "Modern (src/)" || echo "Legacy (app/)"。
环境变量：需要 WORKOS_API_KEY（sk_...）、WORKOS_CLIENT_ID（client_...）、WORKOS_REDIRECT_URI（完整 URL）、WORKOS_COOKIE_PASSWORD（32 位以上）。缺失密码可用 openssl rand -base64 32 生成。默认回调地址为 http://localhost:3000/api/auth/callback。
中间件配置（关键）：authkitMiddleware 必须配置，否则认证会静默失败。服务端中间件应放在 start.ts 的 requestMiddleware 中，不要加到 router.tsx 或 app.tsx 的 createRouter()（那属于仅客户端的 TanStack Router）。若 start.ts 已存在，先读取并在现有 requestMiddleware 数组中加入 authkitMiddleware，保留原有导出风格，不要整文件重写；若不存在，使用 createStart 创建，导出须为命名导出 startInstance（默认导出会导致构建错误），createStart 接收返回配置对象的函数而非配置对象本身。示例：

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

export const startInstance = createStart(() => ({
  requestMiddleware: [authkitMiddleware()],
}));

回调路由（关键）：路径必须与 WORKOS_REDIRECT_URI 匹配。现代扁平路由为 src/routes/api.auth.callback.tsx，旧版嵌套路由为 app/routes/api/auth/callback.tsx。使用 handleCallbackRoute()，不要自写 OAuth 逻辑。示例：

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(),
    },
  },
});

受保护路由：在路由 loader 中使用 getAuth() 检查认证，未登录时通过 getSignInUrl() 获取登录链接并重定向。示例：

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,
});

登出路由：在 loader 中调用 signOut() 后重定向。示例：

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: '/' });
  },
});

客户端 Hook（可选）：仅在组件需要响应式认证状态时使用。在根路由加入 AuthKitProvider：

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

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

在组件中使用 useAuth()：

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

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

多数场景优先使用服务端 getAuth()。

使用方式

创建或编辑文件后必须按顺序执行收尾步骤，否则容易构建失败：

重新生成路由树。新增路由文件会使 routeTree.gen.ts 过期，导致构建出现缺失路由的类型错误。可执行 pnpm build 2>/dev/null || npx tsr generate。
确保存在 Vite 类型声明。TanStack Start 项目通过 import styles from './styles.css?url' 导入 CSS，缺少类型声明会报错。检查 src/vite-env.d.ts（或 app/vite-env.d.ts），如不存在则创建，内容为 /// <reference types="vite/client" />。
执行 pnpm build 验证构建，失败须先修复。常见原因：路由树过期、缺少 Vite 类型、导入路径错误（检查包名是否为 @workos/authkit-tanstack-react-start）。

验证清单（须全部通过）：

grep -r "authkitMiddleware" src/ app/ 2>/dev/null || echo "FAIL: Middleware not configured"
find src/routes app/routes -name "*callback*" 2>/dev/null
grep -c "WORKOS_" .env 2>/dev/null || echo "FAIL: No env vars found"
pnpm build

适用场景

需要在 TanStack Start 全栈 TypeScript 应用中接入 WorkOS AuthKit 登录、回调、受保护路由与登出的开发场景。

限制与错误恢复

“AuthKit middleware is not configured”：原因是 start.ts 中未加入 authkitMiddleware()；修复为创建/更新 src/start.ts 的中间件配置，验证用 grep -r "authkitMiddleware" src/。
SDK “Module not found”：原因是包名错误或未安装；修复为 pnpm add @workos/authkit-tanstack-react-start，验证 ls node_modules/@workos/authkit-tanstack-react-start。
回调 404：原因是路由文件路径与 WORKOS_REDIRECT_URI 不匹配；URI /api/auth/callback 对应 src/routes/api.auth.callback.tsx（扁平）或 app/routes/api/auth/callback.tsx（嵌套），且 createFileRoute() 中的路由字符串必须完全一致。
getAuth 返回 user 为 undefined：原因是中间件未配置或未运行；确保 authkitMiddleware() 在 start.ts 的 requestMiddleware 数组中。
“Cookie password too short”：原因是 WORKOS_COOKIE_PASSWORD 少于 32 位；用 openssl rand -base64 32 生成并更新 .env。
构建出现路由类型错误：原因是新增路由后未重新生成路由树；执行 pnpm dev 重新生成 routeTree.gen.ts。

SDK 导出参考——服务端（主导出）：authkitMiddleware()、handleCallbackRoute()、getAuth()、signOut()、getSignInUrl() / getSignUpUrl()、switchToOrganization()。客户端（/client 子路径）：AuthKitProvider、useAuth()、useAccessToken()。

关于收费、价格、平台支持范围等信息，资料中暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与错误恢复