workos-widgets

WorkOS Widgets

ワークフローの概要

1. 埋め込み型の React コンポーネントと、Client API を直接使用するカスタム開発を区別します。Clerk の UserButton／アカウント関連のリクエストには、完全な同等性を目指すのではなく、実際の Widgets とアプリ固有のメニュー／ナビゲーションのシェルを組み合わせる方法を推奨します。UserSecurity、UserSessions、OrganizationSwitcher については、references/component-setup.md を参照してください。
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 — バージョン確認済みのコンポーネントの役割、機能、インポート、props
• 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 を使用してください。公開されている Widgets は React コンポーネントです。.svelte やその他の React 以外のテンプレートにインポートしないでください。SvelteKit またはその他の React 以外のフロントエンドでは、既存の React 描画境界のみを使用してください。それがない場合は、描画境界を追加するか、Client API を使ってカスタム UI を構築するかを尋ねてください。該当する場合は、関連するウィジェットのリファレンスも読み込んでください（これらは期待される動作を説明するものであり、公開済みコンポーネントの再構築を求めるものではありません）。

• 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

グローバルウィジェットのガイダンス

• 公開済みのコンポーネントは、references/component-setup.md を使用して、React でレンダリングされる UI にのみ埋め込んでください。コンポーネントが内部の 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> 内に配置してください。また、ピア依存関係として @radix-ui/themes と @tanstack/react-query が必要です。accessToken ではなく authToken（文字列または () => Promise<string>）を渡してください。
• モデル定義を重複させず、既存のドメイン型と OpenAPI スキーマを再利用してください。
• ウィジェットのリクエストには、機密性の高いエンドポイントに対する昇格トークンの処理を含む認可レイヤーを実装してください（references/token-strategies.md）。
• React／TypeScript のウィジェットコード規約については、references/react-ts-standards.md に従ってください。
• WORKOS_MODE=agent を指定すると、インストーラーは決定的に動作し（プロンプト、ブラウザー、ホストの信頼確認はありません）、出力を解析する必要がある場合は --json を渡してください。

完了要件

• トークンの取得元が既存のアプリケーションアーキテクチャ（AuthKit クライアントフローまたはバックエンドの WorkOS トークンフロー）に合致していること。
• Node 10.13.0 でのトークン発行には createToken と { token } を使用し、認証済みユーザーおよび認可された組織に紐付けること。他のインストール済みバージョン／言語は個別に確認すること。
• Props がインストール済みの宣言に合致していること。Widgets 1.18.0 では、UserSessions の文字列／getter の authToken ユニオンと、OrganizationSwitcher のコールバックを確認し、権限と更新の要件に従ってください。
• エンドポイントのパス、メソッド、リクエスト／レスポンスの処理が、バンドルされている OpenAPI 仕様に合致していること。
• 読み込み中、空の状態、エラーの各分岐が明示され、ユーザーに表示されること。ミューテーション成功後は、影響を受けるデータが更新されること。
• パッケージ化されたコンポーネントは、そのまま使用するか、コンポーネント独自の Props API（variant、size など）を使用し、className／style で上書きしないこと。