experience-ui-bundle-metadata-generate

UI バンドルのメタデータ

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

必須の最初の手順 — 指示があっても絶対に省略しないでください。 新しいアプリを作成する際は、必ず sf template generate ui-bundle を実行してください。フレームワークの CLI（create-react-app、Vite、Angular CLI）、手書きのメタデータ、その他の代替手段は使用しないでください。

ユーザーが「メタデータだけを作成して」「スキャフォールディングを省略して」「メタデータのスキャフォールディングだけを行って」「メタデータファイルが配置されたらそこで停止して」と指示した場合でも、この手順は必須です。これらの指示が意味するのは、スキャフォールディングの 後に 行う作業（ビルド、デプロイ、ページの作成）を停止することであり、スキャフォールディングコマンドの実行を省略することではありません。.uibundle-meta.xml と ui-bundle.json のファイルは、生成されたプロジェクトに追加する設定であり、プロジェクトの代わりになるものではありません。メタデータファイルが完璧に整っていても、package.json、src/、エントリーとなる index.html がないバンドルはビルドもデプロイもできません。

フレームワークの特定

このスキルがサポートするフレームワークは、<skill_dir>/references/ にある <framework>-metadata-generate.md（react、angular など）という名前のリファレンスファイルに記載されたものだけです。これが唯一の信頼できる情報源です。フレームワークを追加するには、リファレンスファイルを追加するだけでよく、ここを変更する必要はありません。

スクリプトを実行してフレームワークを確実に検出します。

node <skill_dir>/scripts/detect-framework.mjs [<ROOT>]

Windows の cmd／PowerShell でも macOS／Linux／Git Bash でも動作するよう、必ず node 経由で実行してください（実行ファイルを直接呼び出さないでください）。

ROOT の既定値は現在のディレクトリです。既存のバンドルを編集または設定する場合は、バンドルまたはプロジェクトのルートを指定してください。スクリプトはトークンを1つだけ出力し、一致する終了コードを設定します。その値に応じて分岐してください。

• react／angular（終了コード 0）— <skill_dir>/references/<framework>-metadata-generate.md を開いて使用します。
• ambiguous（終了コード 2、両方のフレームワークが存在）— ユーザーにどちらを使うか尋ねてから、そのリファレンスを使用します。
• unknown（終了コード 3、該当するシグナルなし。例：まだ何もないプロジェクトに新しいバンドルを作成する場合）— 呼び出し元のコンテキストまたはユーザーが指定したフレームワークを使用します。それでも決められない場合は <skill_dir>/references/ の内容を一覧表示し、各ファイル名から -metadata-generate.md の接尾辞を取り除いてサポート対象を確認し、ユーザーに選んでもらいます。

呼び出し元のコンテキストまたはユーザーがすでにフレームワークを指定している場合は、検出結果よりもその指定を優先します。ただし、一致するリファレンスファイルが存在することを必ず確認してください。推測してはいけません。

リファレンスファイルには、そのフレームワークで使用する正確な --template フラグ、エントリファイルの構成、置き換える既定のボイラープレート文字列が記載されています。

• UI バンドル名（-n）： 英数字のみを使用してください。スペース、ハイフン、アンダースコア、特殊文字は使用できません。
• テンプレート生成先を変更するには --output-dir を指定します。その場合、以下の手順1で検証スクリプトにも同じパスを指定してください。

生成後：

1. スキャフォールドが完成していることを確認します — プロジェクトのルートから node <skill_dir>/scripts/verify-bundle-location.mjs <BundleName> [<CustomOutputDir>] [<framework>] を実行し、エラーが出力された場合はその内容に従ってください。このスクリプトはバンドルの場所に加え、package.json、src/、エントリとなる index.html が存在することも確認します。いずれかが欠けている場合、スキャフォールドの作成手順が省略されています。先に進む前に sf template generate ui-bundle を実行してください。<CustomOutputDir> はスキャフォールド作成時に --output-dir を使用した場合にのみ指定してください（フレームワークも指定しつつ出力先を省略する場合は "" を指定します）。修復のヒントに正しいテンプレートが表示されるよう、<framework>（react または angular）を指定してください。
2. API バージョンを確認します — プロジェクトのルートから node <skill_dir>/scripts/check-api-version.mjs を実行し、sfdx-project.json の sourceApiVersion が 67.0 以上であることを確認します。必要に応じてスクリプトが自動的に更新します。
3. 既定のボイラープレートをすべて置き換えます。フレームワークのリファレンスファイルに、置き換える正確な既定の <title> とプレースホルダー文字列が記載されています。
4. ホームページに実際のコンテンツを配置します（ランディングセクション、バナー、ヒーロー、ナビゲーション）。
5. ナビゲーションとプレースホルダーを更新します（experience-ui-bundle-frontend-generate スキルを参照）。
6. ホスティングターゲットを設定します — メタ XML に <target> がない UI バンドルは、組織内に表示されません。社内向け（App Launcher）アプリには experience-ui-bundle-custom-app-generate を、外部向け（Experience Site）アプリには experience-ui-bundle-site-generate を使用します。

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

---

UIBundle バンドル

UIBundle バンドルは、必ず force-app/main/default/uiBundles/<AppName>/ に配置してください。SFDX プロジェクトのルートや、その他のパスには作成しないでください。そうしないと、SFDX のデプロイコマンドでバンドルが見つかりません。

バンドルディレクトリには、次のものを含める必要があります。

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

メタ XML

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

Target Field

<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 にも表示されません。必ず次のいずれかとバンドルを組み合わせてください。

• experience-ui-bundle-site-generate（Experience ターゲットの場合）
• experience-ui-bundle-custom-app-generate（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 の形式と命名規則については、references/csp-metadata-format.md に従ってください。force-app/main/default/cspTrustedSites/ に配置します。