implement-saaskit-nextjs

用途

该技能用于在 Next.js App Router 中实现 SaaSKit 登录，使智能体能够为项目添加登录、回调、会话 Cookie、登出和刷新功能。当用户希望使用 SaaSKit Next.js 时适用。

技能按步骤执行：

选择路径：确认是 App Router；若是 Pages Router 或非 Next.js，则改用 implement-saaskit；若是 Django、FastAPI 或 Flask，则改用 implement-saaskit-python。若缺少环境变量，从 app.scalekit.com 的 Developers → Settings → API Credentials 获取四个值，并在 Authentication → Redirect URLs → Allowed callback URLs 注册 SCALEKIT_REDIRECT_URI。
初始化 SDK 和会话 Cookie：仅在仓库尚无 Scalekit SDK 时安装 @scalekit-sdk/node，不添加 jose 或 cookie-parser。创建 lib/scalekit.ts 和 lib/session.ts，使用一个 scalekit_session JSON Cookie。
登录：创建 app/auth/login/route.ts，GET 请求，链接到 /auth/login，不 router.push 到 Scalekit。
回调：将路由放在 SCALEKIT_REDIRECT_URI 指定的路径，默认 /auth/callback → app/auth/callback/route.ts。
登出：创建 app/auth/logout/route.ts，GET 请求，链接到 /auth/logout，并注册 origin 为 Post logout URL。
刷新：创建 app/auth/refresh/route.ts，POST 请求。
保护页面：在项目根目录放置 middleware.ts，仅检查 Cookie 是否存在，不导入 ScalekitClient。然后在 Server Component 中重新检查会话。
停止：不编写 Express cookie-parser 中间件或 Python 认证，不启动 next dev 或运行实时冒烟测试，请用户自行编写 .env，然后停止。

必须在 Server Components 中重新检查会话，仅靠中间件检查 Cookie 存在是不够的。
redirectUri 必须与仪表板中 Allowed callback URL 完全一致。
每个认证 Cookie 必须设置 sameSite: 'lax'，不能使用 'strict'，否则 OAuth 回调时会丢失 Cookie。
next 只能作为相对路径（/...，不能是 //…），不能重定向到任意 URL。
必须在本仓库中写入 App Router 文件后停止，不能运行 create-next-app 或 next dev。
读取 SCALEKIT_ENVIRONMENT_URL、SCALEKIT_CLIENT_ID、SCALEKIT_CLIENT_SECRET 和 SCALEKIT_REDIRECT_URI，不要使用 SCALEKIT_ENV_URL，不要添加 https:// 前缀。
使用一个 scalekit_session JSON HttpOnly Cookie，不要复制 implement-saaskit 中 Express 路径作用域的 Cookie。
ScalekitClient 仅适用于 Node，不要在 middleware.ts（Edge）中导入。
FSA 作用域包含 offline_access。refreshAccessToken 仅返回 { accessToken, refreshToken }。
getLogoutUrl({ idTokenHint, postLogoutRedirectUri })，需注册该登出后 URL。