generating-ui-bundle-metadata

UI バンドルのメタデータ

新しい UI バンドルのスキャフォールディング

新しいアプリを作成するには、汎用的なスキャフォールディングである create-react-app、Vite などではなく、sf template generate ui-bundle を使用してください。

React ベースのバンドルをスキャフォールディングするには、必ず --template reactbasic を渡してください。

UI バンドル名（-n）： 英数字のみを使用してください。スペース、ハイフン、アンダースコア、特殊文字は使用できません。

例：

sf template generate ui-bundle -n CoffeeBoutique --template reactbasic

生成後：

1. デフォルトのボイラープレート（「React App」、「Vite + React」、デフォルトの <title>、プレースホルダーテキスト）をすべて置き換えます
2. ホームページに実際のコンテンツ（ランディングセクション、バナー、ヒーロー、ナビゲーション）を追加します
3. ナビゲーションとプレースホルダーを更新します（building-ui-bundle-frontend スキルを参照）
4. ホスティングターゲットを設定します — meta XML に <target> がない UI バンドルは、組織で表示されません。内部向け（App Launcher）アプリには generating-ui-bundle-custom-app を、外部向け（Experience Site）アプリには generating-ui-bundle-site を使用してください。

UI バンドルのディレクトリでスクリプトを実行する前に、必ず依存関係をインストールしてください。

---

UIBundle バンドル

UIBundle バンドルは uiBundles/<AppName>/ の下に配置し、以下を含める必要があります。

• <AppName>.uibundle-meta.xml — ファイル名はフォルダー名と完全に一致する必要があります
• ビルド出力ディレクトリ（デフォルト：dist/）。少なくとも 1 つのファイルを含めてください

Meta XML

必須フィールド：masterLabel、version（最大 20 文字）、isActive（ブール値）。 任意フィールド：description（最大 255 文字）、target。

Target フィールド

<target> 要素は、UI バンドルのホスティング先を指定します。

値	用途	関連メタデータ
Experience	Digital Experience を介した外部向けサイト	Network、CustomSite、DigitalExperienceConfig、DigitalExperienceBundle
CustomApplication	Lightning App Launcher を介した内部向けアプリ	CustomApplication（applications/*.app-meta.xml）

Salesforce 組織でアプリにアクセスできるようにするには、<target> が必須です。ターゲットなしでデプロイされた UI バンドルは、どこにも表示されません。App Launcher のエントリーも、Experience Site の URL も表示されません。バンドルには、必ず以下のいずれかを組み合わせてください。

• generating-ui-bundle-site（Experience ターゲットの場合）
• generating-ui-bundle-custom-app（CustomApplication ターゲットの場合）

Experience ターゲットの例：

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

CustomApplication ターゲットの例：

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

ui-bundle.json

任意のファイルです。使用できるトップレベルキーは outputDir、routing、headers です。

制約：

• 有効な UTF-8 JSON で、最大 100 KB
• ルートは空でないオブジェクトである必要があります（{}、配列、プリミティブ値は不可）

パスの安全性（outputDir および routing.fallback に適用）：バックスラッシュ、先頭の / または \、.. セグメント、null／制御文字、グロブ（*、?、**）、% は拒否されます。解決後のすべてのパスは、バンドル内に収まる必要があります。

outputDir

サブディレクトリを参照する空でない文字列です（. または ./ は不可）。ディレクトリが存在し、少なくとも 1 つのファイルを含んでいる必要があります。

routing

存在する場合、空でないオブジェクトである必要があります。使用できるキーは rewrites、redirects、fallback、trailingSlash、fileBasedRouting です。

• trailingSlash："always"、"never"、または "auto"
• fileBasedRouting：ブール値
• fallback：パスの安全性を満たす空でない文字列。対象ファイルが存在する必要があります
• rewrites：{ route?, rewrite } オブジェクトの空でない配列。例：{ "route": "/app/:path*", "rewrite": "/index.html" }
• redirects：{ route?, redirect, statusCode? } オブジェクトの空でない配列。statusCode は 301、302、307、308 のいずれかである必要があります

headers

{ source, headers: [{ key, value }] } オブジェクトの空でない配列です。

例：

{
  "routing": {
    "rewrites": [{ "route": "/app/:path*", "rewrite": "/index.html" }],
    "trailingSlash": "never"
  },
  "headers": [
    {
      "source": "/assets/**",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    }
  ]
}

次の形式は絶対に提案しないでください： ルートの {}、空の "routing": {}、空の配列、[{}]、"outputDir": "."、"outputDir": "./"。

---

CSP Trusted Sites

Salesforce は Content Security Policy ヘッダーを適用します。CSP Trusted Site として登録されていない外部ドメインはすべてブロックされます（画像が読み込まれない、API 呼び出しが失敗する、フォントが読み込まれないなど）。

作成するタイミング

アプリが新しい外部ドメインを参照する場合は必ず作成してください。対象には、CDN 画像、外部フォント、サードパーティ API、地図タイル、iframe、外部スタイルシートが含まれます。

手順

1. 外部ドメインを特定する — コード内の各外部 URL からオリジン（スキーム＋ホスト）を抽出します
2. 既存の登録を確認する — force-app/main/default/cspTrustedSites/ を調べます
3. リソースタイプを CSP ディレクティブに対応付ける：

リソースタイプ	ディレクティブフィールド
画像	isApplicableToImgSrc
API 呼び出し（fetch、XHR）	isApplicableToConnectSrc
フォント	isApplicableToFontSrc
スタイルシート	isApplicableToStyleSrc
動画／音声	isApplicableToMediaSrc
iframe	isApplicableToFrameSrc

プリフライト／リダイレクト処理のため、isApplicableToConnectSrc も必ず true に設定します。

4. メタデータファイルを作成する — .cspTrustedSite-meta.xml 形式については implementation/csp-metadata-format.md に従います。force-app/main/default/cspTrustedSites/ に配置します。