generating-ui-bundle-custom-app

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

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

カスタムアプリケーションは Experience Sites とは異なり、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 バージョンと互換性を持つようになります。

必須の呼び出し：

1. CustomApplication に対して get_metadata_type_fields を呼び出し、uiBundle フィールドがあるか確認します
2. UIBundle に対して get_metadata_type_fields を呼び出し、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 ですが、このパスは設定可能です。

ステップ 4：すべてのメタデータフィールドを設定する

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

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

ステップ 4 の実行メモ：ドキュメントを読み込んで使用する

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

ステップ 5：UI Bundle Meta XML を更新する

ステップ 2 で UIBundle に target フィールドが存在することを確認できた場合は、.uibundle-meta.xml ファイルに <target>CustomApplication</target> を追加してください（組織の API バージョンでこのフィールドが存在しない場合は省略してください）。

<?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>

ステップ 6：テンプレート化されていないプロパティを変更しない

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

検証チェックリスト

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

• 必須のプロパティがすべて解決されている
• 利用可能なフィールドを特定するために API コンテキストを照会した（ステップ 2）
• applications/{appName}.app-meta.xml が正しい内容で存在する
• バンドル参照フィールドが組織の API バージョンと一致している（<uiBundle> または <webApplication>）
• target フィールドがサポートされている場合：.uibundle-meta.xml に <target>CustomApplication</target> がある
• デプロイの検証に成功している：

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