workos-widgets

分类: 开发与编程 | 上传者: workos | 下载: 0 | 版本: v1.0（最新）

在现代 Web 应用程序中构建、集成或迁移 WorkOS Widget。在 Next.js、React Router、TanStack Router、TanStack Start、Vite、SvelteKit、Ruby、Python、Go、PHP 或 Java 堆栈中实现用户管理、用户配置文件、管理员门户 SSO 连接或管理员门户域验证小部件时，请使用此技能。检测活动堆栈、身份验证/令牌策略、数据层样式和 UI 约定；然后根据捆绑的 Widgets OpenAPI 规范，通过正确的访问令牌流和 API 调用来实现小部件集成。

更新日志: Source: GitHub https://github.com/workos/skills

目录结构

当前层级: tree/main/plugins/workos/skills/workos-widgets/

📁 references/
- 📁 scripts/
  - 📄 query-spec.cjs 267.4 KB
  - 📄 query-spec.ts 8.1 KB
- 📄 detection.md 3.4 KB
- 📄 fetching-apis.md 6.6 KB
- 📄 framework-go.md 731 B
- 📄 framework-java.md 920 B
- 📄 framework-mixed-repositories.md 446 B
- 📄 framework-nextjs.md 742 B
- 📄 framework-php.md 681 B
- 📄 framework-python.md 754 B
- 📄 framework-react-router.md 674 B
- 📄 framework-ruby.md 648 B
- 📄 framework-sveltekit.md 806 B
- 📄 framework-tanstack-router.md 658 B
- 📄 framework-tanstack-start.md 635 B
- 📄 framework-vite.md 728 B
- 📄 react-ts-standards.md 1.9 KB
- 📄 styling-and-components.md 1.3 KB
- 📄 token-strategies.md 3.3 KB
- 📄 widget-admin-portal-domain-verification.md 536 B
- 📄 widget-admin-portal-sso-connection.md 398 B
- 📄 widget-user-management.md 598 B
- 📄 widget-user-profile.md 328 B
- 📄 widgets-open-api-spec.yaml 86.1 KB
📄 SKILL.md 7.5 KB

SKILL.md

---
name: workos-widgets
description: Build, integrate, or migrate WorkOS Widgets in modern web apps. Use this skill when implementing User Management, User Profile, Admin Portal SSO Connection, or Admin Portal Domain Verification widgets across Next.js, React Router, TanStack Router, TanStack Start, Vite, SvelteKit, Ruby, Python, Go, PHP, or Java stacks. Detect the active stack, auth/token strategy, data-layer style, and UI conventions; then implement widget integration with correct access-token flow and API calls based on the bundled Widgets OpenAPI spec.
---

# WorkOS Widgets

## Workflow Overview

1. Identify widget target from the user request (`user-management`, `user-profile`, `admin-portal-sso-connection`, `admin-portal-domain-verification`).
2. Scan project files in this order:
   - package/dependency manifests
   - framework/router entrypoints
   - auth/token utilities
   - styling/component patterns
3. Detect stack, data-layer style, styling, component system, and package manager using [references/detection.md](references/detection.md).
4. Check for AuthKit/WorkOS presence:
   - if detected, continue;
   - if not detected, ask the user to run `npx workos@latest install`, wait for confirmation, then continue.
5. If detection is ambiguous or conflicting, ask one focused question, then continue.
6. Load only the relevant reference files for the detected stack and widget.
7. Implement integration based on stack shape:
   - frontend route/page + widget component when widget UI lives in the same app
   - token endpoint/service + client integration surface when backend-first/multi-app architecture is detected
8. Validate routing/wiring, imports, and token/API usage before finishing.

## Canonical Inputs

Accept these inputs from the user request when available:

- widget type (or infer from request intent)
- optional component path
- optional page/route path
- optional token endpoint/service preference
- optional constraints (for example: avoid broad refactors)

When input is missing, infer from existing project conventions and detected stack.

## Detection and Ambiguity Protocol

- Apply detection heuristics from [references/detection.md](references/detection.md).
- Explore before asking. Ask only when ambiguity remains after checking manifests and route/auth entrypoints.
- Ask a single concrete question that resolves one decision.
- Default to the strongest detected ownership signals when no user response is available.
- When installs are required, use the package manager detected from project files/lockfiles.

## Reference Loading Map

Always load these core references:

- [references/detection.md](references/detection.md)
- [references/token-strategies.md](references/token-strategies.md)
- [references/fetching-apis.md](references/fetching-apis.md)
- [references/styling-and-components.md](references/styling-and-components.md)

For React/TypeScript stacks (Next.js, React Router, TanStack Router, TanStack Start, Vite), also load:

- [references/react-ts-standards.md](references/react-ts-standards.md)

Load stack-specific reference guidance:

- Next.js: [references/framework-nextjs.md](references/framework-nextjs.md)
- React Router: [references/framework-react-router.md](references/framework-react-router.md)
- TanStack Router: [references/framework-tanstack-router.md](references/framework-tanstack-router.md)
- TanStack Start: [references/framework-tanstack-start.md](references/framework-tanstack-start.md)
- Vite: [references/framework-vite.md](references/framework-vite.md)
- SvelteKit: [references/framework-sveltekit.md](references/framework-sveltekit.md)
- Ruby: [references/framework-ruby.md](references/framework-ruby.md)
- Python: [references/framework-python.md](references/framework-python.md)
- Go: [references/framework-go.md](references/framework-go.md)
- PHP: [references/framework-php.md](references/framework-php.md)
- Java: [references/framework-java.md](references/framework-java.md)
- Mixed repositories: [references/framework-mixed-repositories.md](references/framework-mixed-repositories.md)

Then load exactly one widget reference:

- User Management: [references/widget-user-management.md](references/widget-user-management.md)
- User Profile: [references/widget-user-profile.md](references/widget-user-profile.md)
- Admin Portal SSO Connection: [references/widget-admin-portal-sso-connection.md](references/widget-admin-portal-sso-connection.md)
- Admin Portal Domain Verification: [references/widget-admin-portal-domain-verification.md](references/widget-admin-portal-domain-verification.md)

## Global Widget Guidance

- Implement widget operations using endpoint paths/methods from [references/fetching-apis.md](references/fetching-apis.md). When building request bodies or parsing responses, query the OpenAPI spec for the relevant widget's schemas:
  ```bash
  node references/scripts/query-spec.cjs --widget <widget-name>
  ```
  Use `--list` to see available widget groups.
- Keep loading, empty, and error states explicit and user-visible.
- Keep mutation outcomes visible and refresh/reload affected data after successful changes.
- Align table/list/action UI with existing project conventions.
- Keep behavior resilient for partial/optional data and avoid brittle UI assumptions.

## Core Guidelines

- Reuse existing domain types from the host project and OpenAPI schemas; avoid duplicating model definitions.
- Build widget requests using [references/fetching-apis.md](references/fetching-apis.md) for paths, methods, and schema queries.
- Use direct `fetch`/HTTP calls (or equivalent server HTTP client) for endpoint calls.
- Implement a consistent authorization layer for widget requests, including elevated-token handling for sensitive endpoints when required.
- If the app already uses React Query or SWR, use them as orchestration/cache layers around those direct calls.
- For React/TypeScript widget code quality expectations, follow [references/react-ts-standards.md](references/react-ts-standards.md).
- If AuthKit/WorkOS is missing, prompt the user to run `npx workos@latest install` before continuing.
- Install additional dependencies only when strictly necessary, using the detected package manager/tooling.
- Keep server-state handling aligned with the selected data-layer approach.
- Use local state/reducers for UI interaction state as needed.
- Prefer existing design system and styling conventions.
- Avoid broad unrelated refactors and global style rewrites.

## Completion Requirements

Before finishing, verify all relevant items:

1. Widget component exists and accepts `accessToken: string` when component-level integration is in scope.
2. Route/page wiring is complete when route integration is in scope.
3. Token source matches existing app architecture (AuthKit client flow or backend WorkOS token flow).
4. API methods and paths match the bundled OpenAPI spec, and data-layer usage matches project conventions.
5. Loading and error branches exist for required query/mutation flows.

## Validation Checklist

1. Confirm endpoint paths and HTTP methods come from the bundled OpenAPI spec.
2. Confirm request/response handling follows schema expectations from the spec.
3. Confirm query/mutation invalidation/refetch is applied after successful mutations where required.
4. Confirm empty/error/loading states are explicit and user-visible.
5. Confirm package installs (if any) used the detected package manager/tooling.
6. Confirm implementation stays aligned with existing codebase conventions.
7. Confirm no existing component has been passed `className` or `style` props to override its built-in styling. Use each component as-is or via its own props API (`variant`, `size`, etc.).

登录后下载/点赞/收藏 ❤ 10 | ★ 0

workos-widgets

目录结构

SKILL.md

举报内容

提示