experience-ui-bundle-features-generate

UI バンドル機能

手作業で構築する代わりに、@salesforce/ui-bundle-features CLI を使って、事前にビルドされテスト済みの機能パッケージを Salesforce UI バンドルにインストールします。このファイルはフレームワークに依存しないワークフローの基盤です。例に使うファイル拡張子、機能が書き換えるファイル、機能のエントリーコンポーネントのマウント方法、ビルドコマンドなど、フレームワーク固有の詳細は、<SKILL_DIR>/references/<framework>/ 内のフレームワーク別リファレンスに記載されています。

一から作成する前に、必ず既存の機能を確認してください。CLI はフレームワークに依存せず、検出したバンドルに各機能の適切なフレームワーク向けバリアントをインストールします。現在、最もよく使われているのは認証と検索です。カタログは今後拡充される可能性があるため、最新の一覧を確認するには list --verbose を実行してください。

所有権に関する注意： Agentforce AI 会話クライアントとファイルアップロードは、別のスキル（experience-ui-bundle-agentforce-client-generate、experience-ui-bundle-file-upload-generate）が担当します。カタログに Agentforce またはファイルアップロードの項目も掲載されている場合は、両方からインストールしないでください。どの提供経路を希望するかユーザーに確認し、同じ機能を1つのバンドルに二重にインストールしないでください。

パッケージ名： @salesforce/ui-bundle-features が正式なパッケージ名です。一部の古いテンプレートやサンプルでは、非推奨の @salesforce/ui-bundle-features-experimental という名前が引き続き参照されています。-experimental の接尾辞は絶対に使用しないでください。コマンドでパッケージを解決できない場合は、パッケージ名が誤っていると判断する前に、npm view @salesforce/ui-bundle-features version で公開済みのバージョンを確認してください。

ステップ 0：フレームワークを特定する

<SKILL_DIR> は、このスキル自体のディレクトリ（この SKILL.md を含むフォルダー）の絶対パスです。コンテキスト内のスキルパスから特定してください。

通常、呼び出し元のコンテキストですでにフレームワークが決定されています。このスキルを呼び出したコーディネータースキルから引き継がれているか、ユーザーのリクエストに記載されています。その情報を使用してください。

このスキルがサポートするフレームワークは、<SKILL_DIR>/references/ 内にあるリファレンスフォルダーに限られます。各フォルダーには features.md が含まれています（たとえば react の場合は <SKILL_DIR>/references/react/features.md）。これが唯一の信頼できる情報源です。フレームワークを追加するには、リファレンスフォルダーを追加するだけで済み、このファイルを変更する必要はありません。

• フレームワークが判明している場合 — <SKILL_DIR>/references/<framework>/features.md を開き、この基盤と併せて使用してください。例に使う拡張子、統合対象、マウント例、ビルドコマンドが記載されています。

• フレームワークが不明な場合（誰も指定していない単独実行の場合）— 誰かに尋ねる前に、UI バンドルのルートで決定論的な検出を実行してください。

  bash "<SKILL_DIR>/scripts/detect-framework.sh" "<path-to-uiBundles/<name>/ dir>"
  

  終了コードに応じて分岐してください（説明文を解析しないでください）。

  • react または angular（終了コード 0）→ 該当するフレームワークを使用します。ユーザーに尋ねないでください。検出結果は決定論的です。<SKILL_DIR>/references/<framework>/features.md を開いてください。
  • ambiguous（終了コード 2）→ 両方のフレームワークが存在します。<SKILL_DIR>/references/ の内容を一覧表示し、どのバンドルにインストールするかユーザーに尋ねてください。指定されたフレームワークに対応するリファレンスフォルダーがない場合、このスキルではサポートされていないため、停止してください。
  • unknown（終了コード 3）→ サポート対象のフレームワークが検出されませんでした。終了してください。 バンドル内で React と Angular のどちらのシグナルも見つからず、機能をインストールできないことを伝えて、停止してください。推測しないでください。

以下の手順では、<framework> はここで選択したフォルダーを指します。

ワークフロー

1. まずプロジェクトのコードを検索する — インストールする前に、既存の実装がないか src/ を確認します。検索範囲を src/ に限定し、node_modules/ や dist/ に一致するのを避けます。

2. 利用可能な機能を検索する — --search <query> を指定して npx @salesforce/ui-bundle-features list を実行し、キーワードで絞り込みます。詳細な説明を確認するには --verbose を指定します。

3. 機能を説明する — 配線の前に必ず実行してください。 npx @salesforce/ui-bundle-features describe <feature> を実行し、その出力にある Package: の名前を使って npm view <package> readme を実行し、機能の README を読んでから配線します。README は仕様です。機能の配線方法（ドロップイン可能なエントリーコンポーネントや、各統合例を配置するファイルなど）が記載されています。describe の Copy Operations のコピー先にあるソースと照合してください。そのソースと JSDoc／コメントは、検出されたフレームワークのファイル形式で、実際にインストールされた内容に一致する正確な情報です。ファイル名やコンポーネント API についての思い込みに基づいて配線しないでください。この手順を省略すると、機能のインストールは成功しても実際には動作しないことが最もよくあります。

4. インストールする — npx @salesforce/ui-bundle-features install <feature> --ui-bundle-dir <name> を使います。主なオプション：

   • --dry-run で変更を事前確認します
   • --yes で非対話モードにします（競合をスキップします）
   • --on-conflict error で競合を検出し、その後 --conflict-resolution <file> で解決します

   このバンドルでカスタムのフロントエンド／レイアウト作業を行う前に機能をインストールしてください。機能によってアプリのレイアウトやルーティングのファイル（名前はフレームワークリファレンスを参照）が書き換えられる場合があり、手作業でレイアウトを変更した後にインストールすると衝突するおそれがあります。

一致する機能が見つからない場合は、カスタム実装を作成する前にユーザーに確認してください。関連する機能が別の名前で存在する可能性があります。

競合の処理

非対話環境では、次の2段階の方法を使います。

1. --on-conflict error を指定してインストールを実行し、変更を適用せずに競合を検出します。
2. 解決ファイルを書く前に、references/common/conflict-resolution-schema.json を読み、使用可能なキーと列挙値を確認します。
3. <ui-bundle-dir>/conflict-resolution.json に解決ファイルを作成します（パスはリポジトリのルートではなく、インストール先の UI バンドルディレクトリからの相対パスです）。パスは、1回目の実行で CLI が競合として出力した正確なパスを、そのままキーとして指定します。

   {
     "src/appLayout.tsx": "overwrite",
     "src/routes.tsx": "skip"
   }
   

   （競合パスは、検出されたフレームワークに対して CLI が出力したものです。上記のキーは例です。）一覧にない競合パスはすべて skip が既定値になります。明示的に overwrite に指定していないファイルを CLI が上書きすることはありません。
4. --conflict-resolution <path-to-that-file> を指定してインストールを再実行します。

インストール後：例示ファイルの統合

機能には、統合パターンを示す例示ファイルが __examples__/ ディレクトリ（複数形）に含まれている場合があります。これらは、単なるプレースホルダーテンプレートではなく、具体的な名前を使った、完全に動作するページであることがよくあります（フレームワークリファレンスを参照）。各ファイルについて、次の手順を実行します。

1. 例示ファイルを読んでパターンを把握します。単なるひな形ではなく、動作する参照実装として扱ってください。
2. 対象ファイル（describe の出力に表示されます）を読みます。
3. 例示ファイルのパターンを対象ファイルに適用します。
4. 重要 — 削除する前に確認してください。

   # Verify the build passes with the integrated pattern (build command per framework reference)
   npm run build || {
     echo "ERROR: Build failed after integration - do NOT delete __examples__/"
     exit 1
   }
   
   # Verify the pattern from the example is actually present in the target.
   # Adjust the grep to a key symbol/import/component from the example, over the
   # detected framework's source files (see the framework reference for a worked pattern).
   

   __examples__/ を削除するのは、ビルドが成功し、パターンが対象ファイルに反映されていることの両方を確認した後だけです。

どちらか一方でも確認できない場合は、__examples__/ を削除しないでください。統合を完了させてから、検証を再実行してください。

インストール後：OOTB コンポーネントをマウントし、独自の並行コンポーネントを作成しない

機能に統合ポイントが用意されている場合、UI 必ず独自の並行実装ではなく、その統合ポイントを使用してください。機能にエントリーコンポーネントが用意されている場合は、それをマウントしてください（フレームワークのリファレンスにマウントの慣用例が示されています）。データを直接クエリする独自ページを作成してはいけません。シードデータや生の GraphQL 呼び出しを使った独自の結果ページでは、インストール済みのテスト済み機能を迂回してしまうため、デプロイされた sObject／CMS ロジックが実行されません。唯一の例外は、ユーザーが明示的にオプトアウトして独自のものを求めた場合です。その意図を確認し、推測しないでください。

ヒントのプレースホルダー

一部のコピー先パスでは、CLI が解決しない <descriptive-name> プレースホルダー（例：<desired-page-with-search-input>）を使用しています。インストール後、これらのファイルの名前を変更するか、意図した場所に移動するか、既存のファイルにそのパターンを組み込んでください。これは上記の __examples__/ 規約とは別の仕組みです。1 つのコピー先パスでどちらの仕組みを使うこともできます。

認証機能：組織側の前提条件

認証機能をインストールしても、ファイルがコピーされるだけで、組織は設定されません。これはフレームワークに依存しません（組織／メタデータの設定のみ）。認証が完了したとユーザーに伝える前に、次の組織側の手順がまだ必要であることを伝えてください（このスキルの対象範囲外ですが、機能を実際に動作させるために必要です）。

• Digital Experiences（Experience Cloud）を有効にし、該当するユーザーに Customer Community／Customer Community Plus ライセンスを割り当て、Salesforce Sites を有効にする必要があります。
• コミュニティとゲストのプロファイルに、認証ユーティリティ、ログイン／登録、パスワードリセットの各クラスへの Apex クラスアクセスを明示的に付与する必要があります。CLI はこれを自動では付与しません。
• 認証フローで使用するオブジェクトについて、ゲストプロファイルの共有ルール／組織の共有設定を構成します。
• 既知の制限事項： ログアウトには、文書化されている CSRF 処理の不備（W-21253864 として追跡中）があります。ログアウトが完全に解決済みであるかのように説明せず、ユーザーに伝えてください。

重要：インストールのたびに <sfdxRoot> を解決する

CLI は、未解決のプレースホルダーである、このプロジェクトの Salesforce DX メタデータルート（sfdx-project.json の packageDirectories[].path。例：force-app/main/default）を示すリテラルの <sfdxRoot> フォルダーの下にファイルをコピーすることがあります。そこに残されたファイルはデプロイできません。これはフレームワークに依存しません。

インストールのたびに：

find uiBundles/<AppName> -type d -regex '.*/<[^/]+>$'

該当するファイルが見つかった場合は、それぞれを <metadata-root>/<same-relative-subpath> に移動し（-meta.xml のサイドカーファイルは対応するファイルに付随させてください）、空になったプレースホルダーディレクトリを削除します。

確認：

• find uiBundles/<AppName> -type d -regex '.*/<[^/]+>$' を再実行します。続行前に、出力が空であることを確認してください。