workos-widgets

WorkOS Widgets

Workflow Overview

1. Distinguish embedded React components from direct custom Client API development. For Clerk UserButton / account requests, recommend actual Widgets plus an app-specific menu/navigation shell, not exact parity; UserSecurity, UserSessions and OrganizationSwitcher are covered in references/component-setup.md.
2. Identify the widget target (user-management, user-profile, admin-portal-sso-connection, admin-portal-domain-verification).
3. Detect the stack and whether AuthKit/WorkOS is already present (references/detection.md).
4. If AuthKit/WorkOS is not present, ask the user to run WORKOS_MODE=agent npx workos@latest install, wait for confirmation, then continue.
5. Load the relevant reference files for the detected stack and widget.
6. Implement: a frontend route/page + widget component when the UI lives in the same app, or a token endpoint/service when a backend-first/multi-app architecture is detected.

Reference Loading Map

Always load these core references:

• references/detection.md
• references/component-setup.md — version-checked component roles, capabilities, imports and props
• references/token-strategies.md
• references/fetching-apis.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

Load stack-specific reference guidance:

• 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
• Mixed repositories: references/framework-mixed-repositories.md

For profile/security/sessions/organization selection in a React-rendered UI, use component-setup.md. Published Widgets are React components: do not import them into .svelte or other non-React templates. For SvelteKit or another non-React frontend, use only an existing React rendering boundary; otherwise ask whether to add one or build a custom UI against the Client API. Additionally load the relevant widget reference when applicable (these describe desired behavior, not a mandate to rebuild published components):

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

Global Widget Guidance

• Embed published components only in React-rendered UI using references/component-setup.md; they own their internal API calls.
• For direct custom Client API work, fetch https://workos.com/docs/widgets-api first: current docs use GraphQL POST /client/graphql. Read references/fetching-apis.md for the boundary. The bundled REST spec is a legacy snapshot, not authoritative for all current requests; do not regenerate or migrate API layers just to add a component.
• If the project renders the packaged @workos-inc/widgets components (UsersManagement, UserProfile, AdminPortalSsoConnection, ...), they must sit inside <WorkOsWidgets>, need the peer deps @radix-ui/themes and @tanstack/react-query, and take authToken (a string or () => Promise<string>), not accessToken.
• Reuse existing domain types and OpenAPI schemas rather than duplicating model definitions.
• Implement an authorization layer for widget requests, including elevated-token handling for sensitive endpoints (references/token-strategies.md).
• For React/TypeScript widget code conventions, follow references/react-ts-standards.md.
• WORKOS_MODE=agent keeps the installer deterministic (no prompts, no browser, no host-trust); pass --json when you need to parse its output.

Completion Requirements

• Token source matches the existing app architecture (AuthKit client flow or backend WorkOS token flow).
• Node 10.13.0 token issuance uses createToken and { token }, bound to the authenticated user and authorized organization. Other installed versions/languages are checked independently.
• Props match the installed declarations: for Widgets 1.18.0, check UserSessions' string/getter authToken union and OrganizationSwitcher's callback; respect permission and renewal requirements.
• Endpoint paths, methods, and request/response handling match the bundled OpenAPI spec.
• Loading, empty, and error branches are explicit and user-visible; affected data is refreshed after successful mutations.
• Packaged components are used as-is or via their own props API (variant, size, etc.), not overridden with className/style.