experience-ui-bundle-custom-app-generate

React UI バンドル用のカスタムアプリケーション

Lightning Experience で React UI バンドルをホストする Salesforce カスタムアプリケーションを作成、設定します。このスキルは、アプリが Lightning アプリケーションランチャーに表示され、社内ユーザーがアクセスできるように、CustomApplication メタデータを生成します。

カスタムアプリケーションは Experience サイトとは異なり、Networks、CustomSite、DigitalExperienceConfig、DigitalExperienceBundle メタデータを必要としません。カスタムアプリケーションは、uiBundle で参照される React UI バンドルにレンダリングを委ねる、シンプルなランチャーエントリとして機能します。

必須プロパティ

メタデータを生成する前に、すべてのプロパティを解決してください。それぞれにフォールバックチェーンがあります。値が見つかるまで、各選択肢を順に確認してください。

プロパティ	形式	解決方法
appName	lowercamelcase（例：myInternalApp）	uiBundles/<name>/ ディレクトリにある UI バンドル名
appNamespace	文字列	sfdx-project.json の namespace → sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias} → デフォルトの c
appLabel	人が読みやすい文字列	ユーザー指定の値、または appName をタイトルケースに変換して導出

appNamespace と appName によって、カスタムアプリケーションが正しい React UI バンドルに接続されます。新しい API バージョンでは <uiBundle>{appNamespace}__{appName}</uiBundle> を使用し、古いバージョンでは <webApplication>{appName}</webApplication> を使用します。ここを誤ると、アプリケーションランチャーのエントリは存在しても、ページが空白になります。ワークフローのステップ 2 で、どちらのフィールドを使用するかを判断します。

生成ワークフロー

ステップ 1：すべての必須プロパティを解決する

何かを構築する前に、すべてのプロパティの値を決定します。上の表にある解決方法を使用してください。

ステップ 2：API コンテキストを照会する（バージョンに応じたフィールドの確認）

salesforce-api-context MCP ツールを呼び出して、対象組織の API バージョンで利用できるフィールドを確認します。これにより、生成するメタデータがユーザーの Salesforce バージョンと互換性を持つことを確認できます。

必須の呼び出し — metadataType パラメーターは、以下のとおり正確に使用してください。detail パラメーターやその他の形式に置き換えないでください。このツールが受け付けるパラメーターは metadataType のみです。

1. get_metadata_type_fields({ "metadataType": "CustomApplication" }) — レスポンスのフィールド一覧に uiBundle フィールドがあるか確認します
2. get_metadata_type_fields({ "metadataType": "UIBundle" }) — レスポンスのフィールド一覧に target フィールドがあるか確認します

API レスポンスに基づくフィールドの解決：

フィールドの確認	存在する場合	存在しない場合（古い API バージョン）
CustomApplication.uiBundle	<uiBundle>{appNamespace}__{appName}</uiBundle> を使用します	<webApplication>{appName}</webApplication> を使用します（名前空間なし）
UIBundle.target	<target>CustomApplication</target> を使用します	<target> 要素全体を省略します

実際に試行した後も salesforce-api-context を利用できない場合は、新しいフィールド名（uiBundle と target）を使用します。

ステップ 3：プロジェクト構造を作成する

まだ存在しないファイルやディレクトリを作成します。

メタデータ型	パス
CustomApplication	<sourceDir>/applications/{appName}.app-meta.xml

注： <sourceDir> は sfdx-project.json から決定します。packageDirectories[] を読み取り、"default": true のエントリを使用してください。ソースディレクトリ全体のパスは <path>/main/default です。デフォルトが設定されていない場合は、最初のエントリを使用します。一般的には force-app/main/default ですが、このパスは設定可能です。

Step 4: すべてのメタデータフィールドに値を設定する

以下のドキュメントにあるデフォルトテンプレートを使用します。{braces} 内の値は解決済みのプロパティ参照です。Step 1 の実際の値に置き換えてください。Step 2 のフィールド解決に従って、使用する XML 要素を決定します。

メタデータタイプ	テンプレートの参照先
CustomApplication	configure-metadata-custom-application.md

Step 4 の実行に関する注意：ドキュメントを読み込んで使用する

• エージェントは、メタデータフィールドの設定を試みる前に、Step 4 で参照されている references/*.md ファイルの全内容を必ず読み込んでください。
• ファイル全体を読み込み、プレースホルダー（例：{appName}）を解決済みの値に置き換えてから、展開済みのテンプレートを使用してメタデータ XML の内容を設定します。
• Step 2 で旧フィールド名を使用すると判断された場合は、生成される出力内の <uiBundle> を <webApplication> に置き換えてください。

Step 5: UI Bundle Meta XML を更新する

このステップでは既存のファイルを編集します。新しいファイルは作成しません。UIBundle はバンドル形式のメタデータタイプです。その meta XML は通常、バンドルのほかのソースファイル（例：index.html、src/）とともに、専用フォルダー uiBundles/{appName}/{appName}.uibundle-meta.xml 内にあります。一部の古いプロジェクトや手作業で作成されたプロジェクトでは、代わりにフラットパス uiBundles/{appName}.uibundle-meta.xml（サブフォルダーなし）にある場合があります。

node scripts/resolve-uibundle-path.mjs "{appName}" を実行します。既存の meta XML のパスが出力されます（ネストされたレイアウトを優先し、見つからない場合はフラットレイアウトにフォールバックします）。Windows でも macOS/Linux と同様に動作するよう、必ず node 経由で実行してください（実行可能ファイルを直接実行しないでください）。そのファイルを指定どおりの場所で編集してください。別のパスに2つ目のファイルを作成したり、このスキルの一環として別のレイアウトに移行したりしないでください。

Step 2 で UIBundle に target フィールドが存在すると確認された場合は、そのファイルの既存の <UIBundle> 要素内に <target>CustomApplication</target> を追加し、ほかの既存要素と値はすべて変更せずに保持してください（組織の API バージョンにこのフィールドが存在しない場合は、このステップ全体を省略してください。その場合、ファイルを作成したり <target> を追加したりしないでください）。

次のことは禁止されています：

• 新しい .uibundle-meta.xml ファイルを作成すること
• 既存の .uibundle-meta.xml ファイルがどこかにある場合（ネストまたはフラット）、別のパスに2つ目の .uibundle-meta.xml ファイルを作成すること。既存のファイルをその場で編集してください
• <target> を別の場所に追加しつつ、元の uiBundles/{appName}/{appName}.uibundle-meta.xml（または既存のレイアウトがフラットの場合は uiBundles/{appName}.uibundle-meta.xml）を変更しないこと

このスキルが生成または変更するファイルは applications/{appName}.app-meta.xml（新規）と既存の {appName}.uibundle-meta.xml（<target> が適用される場合に限り、その場で編集）のみです。出力にほかの UI バンドル関連ファイルが含まれている場合は、バグです。

更新後のファイルの例（uiBundles/{appName}/{appName}.uibundle-meta.xml、または既存のレイアウトがフラットの場合はフラットパス）。これは既存のファイルの最終状態を示すものであり、新規作成するファイルではありません：

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>{appName}</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>

Step 6: テンプレート化されていないプロパティは変更しない

CustomApplication メタデータのうち、{braces} で囲まれた変数として表されていないデフォルトのプロパティ値は変更しないでください。

検証チェックリスト

デプロイ前に、次の項目を確認してください：

• 必須のプロパティがすべて解決されている
• 使用可能なフィールドを判断するため、API コンテキストが照会されている（Step 2）
• applications/{appName}.app-meta.xml が正しい内容で存在する
• バンドル参照フィールドが組織の API バージョンと一致している（<uiBundle> または <webApplication>）
• target フィールドがサポートされている場合：既存の {appName}.uibundle-meta.xml（uiBundles/{appName}/ 内のネストされたパス、または uiBundles/ 内のフラットパスのうち、既存のパス）に <target>CustomApplication</target> がある
• 余分な .uibundle-meta.xml ファイルが作成されていない。既存の場所に {appName}.uibundle-meta.xml が1つだけ存在する
• デプロイが正常に検証される：

sf project deploy validate --metadata CustomApplication UIBundle --target-org ${usernameOrAlias}