building-ui-bundle-app

UI バンドルアプリの構築

概要

自然言語による説明をもとに、依存関係の正しい順序で専用の UI バンドルスキルを連携させ、デプロイ可能な Salesforce React UI バンドルアプリを構築します。各スキルは、該当するフェーズを実行する前に必ず明示的に読み込む必要があります。

このスキルを使用するタイミング

次の場合に使用します：

• ユーザーが Salesforce 上で「React アプリ」、「UI バンドル」、「ウェブアプリ」、「フルスタックアプリ」を求めている
• ユーザーが「アプリを構築して」、「アプリケーションを作成して」と言い、文脈から LWC ベースではないフロントエンド（例：React）が必要だとわかる
• 作業によって、単独のコンポーネントではなく、スキャフォールディング、機能、データアクセス、UI を備えた完全な UI バンドルが作成される

このスキルを使用する例：

• 「Salesforce のデータを使って顧客ケースを管理する React アプリを構築して」
• 「検索とナビゲーション機能を備えた従業員名簿の UI バンドルを作成して」
• 「認証、データテーブル、ファイルアップロード機能を備えたフルスタック React アプリが必要です」
• 「Salesforce 上にコーヒーショップの注文アプリを構築して」

次の場合は使用しないでください：

• 単一のページまたはコンポーネントを作成する場合（building-ui-bundle-frontend を使用）
• 機能のインストールのみを行う場合（generating-ui-bundle-features を使用）
• データアクセスのセットアップのみを行う場合（using-ui-bundle-salesforce-data を使用）
• 既存のアプリのデプロイのみを行う場合（deploying-ui-bundle を使用）
• カスタムオブジェクトとメタデータを備えた Lightning Experience アプリを構築する場合（generating-lightning-app を使用）
• 既存の UI バンドルのトラブルシューティングやデバッグを行う場合

---

依存関係グラフとビルド順序

フェーズ 1：スキャフォールディング（基盤）

UI Bundle scaffold (sf template generate ui-bundle)
    v
Install dependencies (npm install)
    v
Bundle metadata (uibundle-meta.xml, ui-bundle.json)
    v
CSP Trusted Sites (if external domains needed)

UI バンドルのディレクトリ構造、メタ XML、任意のルーティング／ヘッダー設定を作成します。以降のすべてのフェーズを実行するには、スキャフォールドが存在している必要があります。

フェーズ 2：機能（任意）

Search project code (src/) for existing implementations
    v
Install dependencies (npm install)
    v
Search, describe, and install features (auth, shadcn, search, navigation, GraphQL)
    v
Resolve conflicts (two-pass: --on-conflict error, then --conflict-resolution)
    v
Integrate __example__ files into target files, then delete them

事前構築済みのテスト済み機能パッケージをインストールします。アプリで事前構築済みの機能が不要な場合はスキップしてください。ゼロから構築する前に、既存の機能がないか必ず確認してください。機能は、UI コンポーネントを構築するための基盤となります。

フェーズ 3：データアクセス（バックエンドの接続）

Acquire schema (npm run graphql:schema)
    v
Look up entity schema (graphql-search.sh, max 2 runs)
    v
Generate queries/mutations (use verified field names, @optional on all record fields)
    v
Validate and test (npx eslint, ask user before testing mutations)

@salesforce/sdk-data を使用してデータレイヤーをセットアップします。レコード操作には GraphQL を推奨し、Connect、Apex、または UI API エンドポイントには REST を使用します。

フェーズ 4：UI（フロントエンド）

Layout, navigation, header, and footer (appLayout.tsx)
    v
Pages (routed views)
    v
Components (widgets, forms, tables)

React UI を構築します。フェーズ 3 のデータレイヤーとフェーズ 2 の機能を参照します。すべてのボイラープレートとプレースホルダーコンテンツを置き換える必要があります。

フェーズ 5：インテグレーション（任意）

Agentforce chat widget (if requested)
File upload API (if requested)

これらは互いに独立しているため、両方が必要な場合は並行して実行できます。

フェーズ 6：デプロイ

Org authentication
    v
Pre-deploy UI bundle build (npm install + npm run build)
    v
Deploy metadata
    v
Post-deploy configuration (permissions, profiles, named credentials, connected apps, custom settings, flow activation)
    v
Import data (if data plan exists)
    v
Fetch GraphQL schema and run codegen
*(Re-fetches schema from the deployed org -- required because the remote schema may differ from the local one used in Phase 3)*
    v
Final UI bundle build (rebuilds with the deployed schema)

標準の 7 ステップのデプロイ手順に従います。スキーマを取得する前にメタデータをデプロイする必要があります。スキーマを取得する前に権限を割り当てる必要があります。

フェーズ 7：ホスティング先

アプリの対象ユーザーに応じて、次のいずれか1 つを選択します。

フェーズ 7a：Experience Site（外部向け）

Resolve site properties (siteName, appDevName, etc.)
    v
Generate site metadata (Network, CustomSite, DigitalExperience)
    v
Deploy site infrastructure

UI バンドルをホストする Digital Experience サイトを作成します。外部ユーザー向けの公開 URL または認証が必要なサイト URL をユーザーが求めている場合に使用します。

フェーズ 7b：カスタムアプリケーション（内部向け）

Resolve app properties (appName, appNamespace, appLabel)
    v
Generate CustomApplication metadata (applications/*.app-meta.xml)
    v
Add <target>CustomApplication</target> to .uibundle-meta.xml
    v
Deploy custom application

Lightning App Launcher にカスタムアプリケーションのエントリを作成します。Lightning Experience 内でアクセスする内部ユーザー向けのアプリの場合に使用します。

---

実行ワークフロー

ステップ 1：要件の分析と計画

実施事項：

1. ユーザーの自然言語による依頼を解析する
2. アプリ名と目的を特定する
3. ページとナビゲーション構造を抽出する
4. 必要なデータエンティティと Salesforce オブジェクトを特定する
5. 必要な機能（認証、検索、ファイルアップロード、チャット）を検出する
6. Experience Site が必要かどうかを判断する
7. CSP 登録が必要な外部ドメインを特定する

出力：ビルド計画

UI Bundle App Build Plan: [App Name]

SCAFFOLDING:
- App name: [PascalCase name]
- Routing: [SPA rewrites, trailing slash config]
- External domains: [domains needing CSP registration]

FEATURES:
- [list of features to install: auth, shadcn, search, navigation, etc.]

DATA ACCESS:
- Objects: [Salesforce objects to query/mutate]
- Queries: [list of GraphQL queries needed]
- REST endpoints: [Apex REST or Connect API calls, if any]

UI:
- Layout: [description of app shell/navigation]
- Pages: [list of pages with routes]
- Components: [key components per page]
- Design direction: [aesthetic/style intent]

INTEGRATIONS (if applicable):
- Agentforce chat: [yes/no, agent ID if known]
- File upload: [yes/no, record linking pattern]

DEPLOYMENT:
- Target org: [org alias if known]
- Hosting target: [Experience Site / Custom Application / none]

SKILL LOAD ORDER:
1. generating-ui-bundle-metadata
2. generating-ui-bundle-features (if features needed)
3. using-ui-bundle-salesforce-data (if data access needed)
4. building-ui-bundle-frontend
5a. implementing-ui-bundle-agentforce-conversation-client (if chat requested)
5b. implementing-ui-bundle-file-upload (if file upload requested)
6. deploying-ui-bundle
7a. generating-ui-bundle-site (if Experience Site requested -- external users)
7b. generating-ui-bundle-custom-app (if Custom Application requested -- internal users)

ステップ 2：フェーズごとの実行

各フェーズを順番に実行します。次のフェーズに進む前に、フェーズ内のすべての手順を完了してください。各フェーズでは、次の手順を行います。

手順	実行内容	理由
1. スキルを読み込む	このフェーズのスキルを（Skill ツールなどを使って）呼び出します	現在のルール、パターン、制約、実装ガイドを確認できます
2. 実行する	読み込んだスキルのワークフローに従って、コード／設定を生成します	正しく作業する方法はスキルで定義されています
3. 検証する	UI バンドルディレクトリから lint とビルドを実行します	次のフェーズに進む前にエラーを検出できます
4. チェックポイント	次に進む前にフェーズの完了を確認します	次のフェーズの依存関係が満たされていることを確認できます

手順 1（スキルの読み込み）を省略しないでください。 スキルの内容を覚えていても、内容は更新されます。必ず最新バージョンを読み込んでください。

---

フェーズ 1 -- スキャフォールディング

• 1. スキルを読み込む：generating-ui-bundle-metadata を呼び出します
• 2. 実行する：sf template generate ui-bundle を実行し、依存関係をインストールして（npm install）、メタ XML、ui-bundle.json、CSP の信頼済みサイトを設定します
• 3. 検証する：ディレクトリ構造とメタデータファイルが存在することを確認します
• 4. チェックポイント：UI バンドルのスキャフォールドが準備できたら、フェーズ 2 に進みます

フェーズ 2 -- 機能（事前構築済みの機能が不要な場合はスキップ）

• 1. スキルを読み込む：generating-ui-bundle-features を呼び出します
• 2. 実行する：依存関係をインストールし、機能を検索してインストールし、サンプルファイルを統合します
• 3. 検証する：npm run build を実行し、機能が問題なく統合されていることを確認します
• 4. チェックポイント：機能のインストールが完了したら、フェーズ 3 に進みます

フェーズ 3 -- データアクセス（Salesforce データが不要な場合はスキップ）

• 1. スキルを読み込む：using-ui-bundle-salesforce-data を呼び出します
• 2. 実行する：スキーマを取得し、エンティティを調べ、クエリ／ミューテーションを生成して、コンポーネントに組み込みます
• 3. 検証する：GraphQL クエリを含むファイルに対して npx eslint を実行します
• 4. チェックポイント：データレイヤーの準備ができたら、フェーズ 4 に進みます

フェーズ 4 -- UI

• 1. スキルを読み込む：building-ui-bundle-frontend を呼び出します
• 2. 実行する：レイアウト、ページ、コンポーネント、ナビゲーションを構築します。ボイラープレートはすべて置き換えます。
• 3. 検証する：lint とビルドを実行します。エラーが 0 件であることが必須です
• 4. チェックポイント：UI が完成したら、フェーズ 5 に進みます

フェーズ 5 -- インテグレーション（依頼されていない場合はスキップ）

• 1. スキルを読み込む：implementing-ui-bundle-agentforce-conversation-client（5a）および／または implementing-ui-bundle-file-upload（5b）を呼び出します。両方が必要な場合は、それぞれ独立しているため、並行して実行できます。
• 2. 実行する：各スキルのワークフローに従ってインテグレーションを追加します
• 3. 検証する：lint とビルドを実行します
• 4. チェックポイント：インテグレーションが完了したら、フェーズ 6 に進みます

フェーズ 6 -- デプロイ

• 1. スキルを読み込む：deploying-ui-bundle を呼び出します
• 2. 実行する：7 ステップのデプロイ手順（認証、ビルド、デプロイ、権限、データ、スキーマ、最終ビルド）に従います
• 3. 検証する：デプロイが成功し、アプリにアクセスできることを確認します
• 4. チェックポイント：アプリをデプロイしたら、必要に応じてフェーズ 7 に進みます

フェーズ 7a -- Experience Site（依頼されていない場合、または Custom Application を選択した場合はスキップ）

• 1. スキルを読み込む：generating-ui-bundle-site を呼び出します
• 2. 実行する：プロパティを解決し、サイトのメタデータを生成して、デプロイします
• 3. 検証する：サイトの URL にアクセスできることを確認します
• 4. チェックポイント：サイトが公開されたら、ビルド完了です

フェーズ 7b -- Custom Application（依頼されていない場合、または Experience Site を選択した場合はスキップ）

• 1. スキルを読み込む：generating-ui-bundle-custom-app を呼び出します
• 2. 実行する：アプリのプロパティを解決し、CustomApplication メタデータを生成して、メタ XML に CustomApplication ターゲットを追加します
• 3. 検証する：アプリランチャーにアプリが表示されることを確認します
• 4. チェックポイント：アプリが登録されたら、ビルド完了です

ステップ 3：最終サマリー

すべてのフェーズが完了したら、ビルドの概要を提示します。

UI Bundle App Build Complete: [App Name]

PHASES COMPLETED:
[x] Phase 1: Scaffolding -- [app name] UI bundle created
[x] Phase 2: Features -- [list of features installed, or "skipped"]
[x] Phase 3: Data Access -- [list of entities wired up]
[x] Phase 4: UI -- [count] pages, [count] components
[x] Phase 5: Integrations -- [list or "none"]
[x] Phase 6: Deployment -- deployed to [org]
[x] Phase 7: Hosting Target -- [Experience Site URL / Custom Application name / "skipped"]

FILES GENERATED:
[list key files and their paths]

NEXT STEPS:
[any manual steps the user should take]

---

検証

ビルドが完了したと提示する前に、以下を確認してください。

• スキャフォールドが存在する：有効なメタ XML と ui-bundle.json を含む UI バンドルディレクトリがある
• 依存関係がインストールされている：node_modules/ が存在し、package.json に想定されるパッケージが含まれている
• ビルドが成功する：npm run build を実行すると、エラーなしで dist/ が生成される
• Lint が成功する：npx eslint src/ でエラーが 0 件と報告される
• ボイラープレートが残っていない：すべてのプレースホルダーテキスト、デフォルトのタイトル、テンプレートコンテンツが置き換えられている
• ナビゲーションが機能する：appLayout.tsx に、作成したページと一致する実際のナビ項目がある
• データレイヤーが接続されている：データアクセスのフェーズを実行した場合、コンポーネントで @salesforce/sdk-data を使用している
• CSP が登録されている：該当する場合、すべての外部ドメインに CSP Trusted Site メタデータが設定されている

---

エラー処理

カテゴリー 1：停止してユーザーに確認する

• アプリの目的が曖昧すぎて、ページやデータの要件を特定できない
• ユーザーが互いに矛盾する機能を求めている（例：「認証なし」と「ユーザー固有のデータを表示する」）
• 対象の組織が不明なまま、デプロイが要求されている

カテゴリー 2：警告を記録して続行する

• 機能のインストールで軽微な競合が発生する（解決して続行する）
• オプションのインテグレーション設定で、処理を妨げない問題が発生する
• ビルドでエラー以外の警告が発生する

---

ベストプラクティス

1. フェーズの順序を必ず守る

機能をインストールする前に UI を構築しないでください。ビルドする前にデプロイしないでください。依存関係の順序は厳守してください。

2. ボイラープレートをすべて置き換える

生成するアプリはすべて、用途に特化したものにしてください。「React App」というタイトル、「Vite + React」というプレースホルダー、その他すべてのデフォルトコンテンツを、実際のアプリ固有のテキストやブランディングに置き換えてください。

3. 意図を持ってデザインする

building-ui-bundle-frontend のデザイン思考とフロントエンドの美観に関するガイダンスに従ってください。すべてのアプリに明確なビジュアルの方向性を持たせ、汎用的なデフォルト設定にしないでください。