canvas-workbench

プロジェクトの種類

このスキルを適用する前に、package.json に @drupal-canvas/headless という依存関係、または @drupal-canvas/headless- で始まる依存関係があるか確認してください。該当する依存関係がある場合、これは Canvas Headless のコードベースです。まず canvas-headless を読んでください。Workbench は現在、React プロジェクトのみをサポートしています。React のヘッドレスプロジェクト（Next.js、TanStack Start）では使用できますが、Nuxt および Astro プロジェクトでは、代わりにフレームワークの開発サーバーを通じてコンポーネントを確認してください。該当する依存関係がない場合、これは Canvas がレンダリングする React コードベースです。コンポーネントは React（index.jsx／.tsx）であり、このスキルの内容はすべて記載どおりに適用されます。プロジェクトの種類はこの2つのみです。

インストールの確認

Workbench を使用する前に、プロジェクトのパッケージマネージャーを特定し、対応する実行コマンドで @drupal-canvas/workbench を使用してください。

推奨コマンド：

• npm：npx @drupal-canvas/workbench
• pnpm：pnpm dlx @drupal-canvas/workbench
• bun：bunx @drupal-canvas/workbench
• yarn：yarn dlx @drupal-canvas/workbench

リポジトリのパッケージマネージャーに合ったコマンドを選択してください。ロックファイルと既存のプロジェクトの慣例を参考に判断してください。

パッケージ実行コマンドまたは @drupal-canvas/workbench が利用できない場合は、作業を中止し、現在の環境では Canvas Workbench を利用できないことをユーザーに伝えてください。インストールするかどうか尋ねてください。インストールするとの返答があった場合は、対応するパッケージマネージャーで @drupal-canvas/workbench を開発依存関係としてインストールしてください。

• npm：npm install --save-dev @drupal-canvas/workbench
• pnpm：pnpm add --save-dev @drupal-canvas/workbench
• bun：bun add --dev @drupal-canvas/workbench
• yarn：yarn add --dev @drupal-canvas/workbench

インストールが完了したら、対応する実行コマンドを使用し、Workbench による検証を続けてください。ユーザーがインストールしないと答えた場合は作業を中止し、別の起動コマンドを推測して使用しないでください。

設定の確認

プロジェクトが Canvas のデフォルトのレイアウトを使用している場合、Workbench に canvas.config.json ファイルは不要です。

Workbench を起動する前に、プロジェクトがデフォルトのパスを使用しているか確認してください。

• componentDir：プロジェクトのルート
• pagesDir：./pages
• aliasBaseDir：src
• globalCssPath：./src/components/global.css

プロジェクトがこれらのデフォルトを使用していて、canvas.config.json が存在しない場合は、作成せずに進めてください。

プロジェクトで異なるコンポーネントのパス、ページのパス、@/ のインポート解決、またはグローバル CSS のエントリーポイントを使用している場合は、Workbench を起動する前にプロジェクトのルートに canvas.config.json を追加するか更新してください。プロジェクトに必要なオプションのみを設定してください。

例：

{
  "componentDir": "./src/components",
  "pagesDir": "./pages",
  "aliasBaseDir": "src",
  "globalCssPath": "./src/global.css"
}

Workbench の起動

Workbench による検証が必要で、パッケージ実行コマンドが利用できる場合：

1. プロジェクトのルートから、対応する Workbench コマンドを実行します。
2. これを長時間実行されるローカル開発サーバープロセスとして扱います。
3. 起動時の出力を確認し、表示されたローカル URL を使用します。
4. 結果を検証している間は、サーバーを実行したままにします。

現在のプロジェクトで Workbench サーバーがすでに実行中の場合は、2つ目のインスタンスを起動せずに再利用してください。

ページ、サイト、クライアントのコンテキスト

インタラクティブプレビューと preview-build の出力は、usePageContext()、useSiteContext()、useJsonApiClient() のプロバイダーを自動的に提供します。これらのフックを機能させるために、コンポーネントレベルのプロバイダーを追加したり、Drupal のグローバル変数を注入したりしないでください。サイトデータとクライアント設定は、Vite 統合の公開リクエスト /canvas/api/v0/site-data から取得され、既存の設定にフォールバックします。

Workbench は、現在の Drupal ページのコンテキストを読み込みません。意図的に設定されているページのデフォルトは次のとおりです。

{ pageTitle: '', breadcrumbs: [], mainEntity: null }

そのため、パンくずリストが空だったり、エンティティに依存するコンポーネントが非表示になったりするのは、正しい場合があります。実際のページコンテキストは Drupal またはルーティングされたヘッドレスアプリケーションで確認してください。これらのデフォルトを隠すために、コンポーネントのモックで JSON:API ペイロードやページコンテキストのフィクスチャを作り込まないでください。実際のローディング状態、空の状態、エラー状態を引き続き使用してください。

既存のモックを編集すると、マウント済みのプレビューがその場で更新され、コンポーネントの状態は保持されます。ディスカバリーファイルを追加または削除すると、iframe が再マウントされる場合があります。初期状態を確認する場合は、モックの編集によってリセットされたと思い込まず、明示的に再読み込みしてください。

検証ワークフロー

Workbench はローカルプレビュー検証の実行環境です。検証を繰り返す場合は、修正とレビューの各ループで同じ Workbench サーバーとプレビュールートを再利用してください。

通常の実装ループの一環として Workbench を使用してください。

1. Workbench を起動するか、既存のものを再利用します。
2. 該当するコンポーネントのプレビュー状態またはページプレビューを開きます。
3. 要求された変更が正しく表示されることを確認します。
4. 結果が正しくない場合は実装を更新し、再度確認します。
5. Workbench での検証に合格した後にのみ完了とするか、検証を妨げた要因を明確に説明します。

対象範囲

このスキルは、Workbench の起動と使用、およびページ／モックの作成を調整するためのものです。Canvas コンポーネントの仕様を定義するものではありません。

• コンポーネントの構造、component.yml、命名、モックの網羅性に関する要件の作成または検証には、canvas-component-definition を使用します。
• ページ JSON ファイル、ページ構造、ページスキーマの要件の作成または検証には、canvas-page-definition を使用します。
• mocks.json の作成または検証が必要な場合は、canvas-component-definition/references/component-mocks.md を使用します。
• Workbench 固有のコンポーネントレビューフローと、コンポーネントのプレビューファイルの配置場所については、references/components.md を使用します。
• Workbench 固有のページプレビューフローと、設定されたページの配置場所については、references/pages.md を使用します。