workos-widgets

WorkOS 小组件

工作流概述

1. 区分嵌入式 React 组件与直接使用 Client API 进行自定义开发。对于 Clerk UserButton / 账户相关请求，建议使用实际的小组件搭配应用专属的菜单/导航外壳，而非追求完全一致；references/component-setup.md 涵盖了 UserSecurity、UserSessions 和 OrganizationSwitcher。
2. 确定小组件目标（user-management、user-profile、admin-portal-sso-connection、admin-portal-domain-verification）。
3. 检测技术栈，以及是否已集成 AuthKit/WorkOS（references/detection.md）。
4. 如果尚未集成 AuthKit/WorkOS，请让用户运行 WORKOS_MODE=agent npx workos@latest install，等待确认后再继续。
5. 加载与检测到的技术栈和小组件相关的参考文件。
6. 实施：如果 UI 位于同一应用中，则添加前端路由/页面和小组件；如果检测到以后端为先或多应用架构，则添加令牌端点/服务。

参考文件加载映射

始终加载以下核心参考文件：

• references/detection.md
• references/component-setup.md — 经版本核验的组件角色、功能、导入方式和属性
• references/token-strategies.md
• references/fetching-apis.md
• references/styling-and-components.md

对于 React/TypeScript 技术栈（Next.js、React Router、TanStack Router、TanStack Start、Vite），还需加载：

• references/react-ts-standards.md

加载特定技术栈的参考指南：

• Next.js：references/framework-nextjs.md
• React Router：references/framework-react-router.md
• TanStack Router：references/framework-tanstack-router.md
• TanStack Start：references/framework-tanstack-start.md
• Vite：references/framework-vite.md
• SvelteKit：references/framework-sveltekit.md
• Ruby：references/framework-ruby.md
• Python：references/framework-python.md
• Go：references/framework-go.md
• PHP：references/framework-php.md
• Java：references/framework-java.md
• 混合仓库：references/framework-mixed-repositories.md

对于 React 渲染的 UI 中的个人资料/安全/会话/组织选择功能，请使用 component-setup.md。已发布的小组件是 React 组件：不要将其导入 .svelte 或其他非 React 模板。对于 SvelteKit 或其他非 React 前端，只能使用现有的 React 渲染边界；否则，请询问用户是要添加一个渲染边界，还是基于 Client API 构建自定义 UI。此外，在适用时加载相关的小组件参考文件（这些文件描述的是预期行为，并不要求重建已发布的组件）：

• 用户管理：references/widget-user-management.md
• 用户资料：references/widget-user-profile.md
• 管理门户 SSO 连接：references/widget-admin-portal-sso-connection.md
• 管理门户域名验证：references/widget-admin-portal-domain-verification.md

全局组件指导

• 仅在 React 渲染的 UI 中嵌入已发布的组件，并遵循 references/component-setup.md；这些组件会自行处理内部 API 调用。
• 直接自定义调用 Client API 时，请先获取 https://workos.com/docs/widgets-api：当前文档使用 GraphQL POST /client/graphql。请阅读 references/fetching-apis.md，了解适用范围。随附的 REST 规范是旧版快照，不能作为所有当前请求的权威依据；不要仅为添加组件而重新生成或迁移 API 层。
• 如果项目渲染打包的 @workos-inc/widgets 组件（UsersManagement、UserProfile、AdminPortalSsoConnection 等），必须将它们放在 <WorkOsWidgets> 内部，需要 peer 依赖 @radix-ui/themes 和 @tanstack/react-query，并传入 authToken（字符串或 () => Promise<string>），而不是 accessToken。
• 复用现有领域类型和 OpenAPI 架构，而非重复定义模型。
• 为组件请求实现授权层，包括对敏感端点处理高权限令牌（references/token-strategies.md）。
• React/TypeScript 组件代码规范请遵循 references/react-ts-standards.md。
• WORKOS_MODE=agent 可确保安装程序行为确定（不显示提示、不打开浏览器、不信任主机）；需要解析其输出时，请传入 --json。

完成要求

• 令牌来源符合现有应用架构（AuthKit 客户端流程或后端 WorkOS 令牌流程）。
• Node 10.13.0 的令牌签发使用 createToken 和 { token }，并绑定到已认证用户及获授权的组织。其他已安装版本／语言需单独检查。
• 属性与已安装的声明相符：对于 Widgets 1.18.0，请检查 UserSessions 的字符串／getter authToken 联合类型及 OrganizationSwitcher 的回调；遵循权限和续期要求。
• 端点路径、方法以及请求／响应处理与随附的 OpenAPI 规范相符。
• 明确呈现加载、空状态和错误分支，并在成功执行变更后刷新受影响的数据。
• 原样使用打包的组件，或通过其自身的属性 API（variant、size 等）使用；不要用 className／style 覆盖组件。