building-ui-bundle-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building a UI Bundle App

构建UI Bundle应用

Overview

概述

Build a complete, deployable Salesforce React UI bundle application from a natural language description by orchestrating specialized UI bundle skills in correct dependency order. Each skill MUST be explicitly loaded before executing its phase.

通过按照正确的依赖顺序协调专用UI bundle技能，根据自然语言描述构建完整的、可部署的Salesforce React UI bundle应用。在执行每个阶段之前，必须显式加载对应的技能。

When to Use This Skill

何时使用此技能

Use when:

User requests a "React app", "UI bundle", "web app", or "full-stack app" on Salesforce
User says "build an app", "create an application" and the context implies a non-LWC based frontend (e.g. React)
The work produces a complete UI bundle with scaffolding, features, data access, and UI -- not a single component in isolation

Examples that should trigger this skill:

"Build a React app for managing customer cases with Salesforce data"
"Create a UI bundle for an employee directory with search and navigation"
"I need a full-stack React app with authentication, data tables, and file uploads"
"Build a coffee shop ordering app on Salesforce"

Do NOT use when:

Creating a single page or component (use
```
building-ui-bundle-frontend
```
)
Only installing a feature (use
```
generating-ui-bundle-features
```
)
Only setting up data access (use
```
using-ui-bundle-salesforce-data
```
)
Only deploying an existing app (use
```
deploying-ui-bundle
```
)
Building a Lightning Experience app with custom objects and metadata (use
```
generating-lightning-app
```
)
Troubleshooting or debugging an existing UI bundle

适用场景：

用户请求在Salesforce上构建「React app」「UI bundle」「web app」或「full-stack app」
用户提出「build an app」「create an application」，且上下文暗示基于非LWC的前端（如React）
工作产出包含脚手架、功能、数据访问和UI的完整UI bundle，而非孤立的单个组件

应触发此技能的示例：

"构建一个用于管理Salesforce客户案例的React应用"
"创建一个带有搜索和导航功能的员工目录UI bundle"
"我需要一个包含认证、数据表和文件上传功能的全栈React应用"
"在Salesforce上构建一个咖啡店点餐应用"

请勿使用场景：

创建单个页面或组件（请使用
```
building-ui-bundle-frontend
```
）
仅安装功能（请使用
```
generating-ui-bundle-features
```
）
仅设置数据访问（请使用
```
using-ui-bundle-salesforce-data
```
）
仅部署现有应用（请使用
```
deploying-ui-bundle
```
）
构建带有自定义对象和元数据的Lightning Experience应用（请使用
```
generating-lightning-app
```
）
排查或调试现有UI bundle

Dependency Graph & Build Order

依赖关系图与构建顺序

Phase 1: Scaffolding (Foundation)

阶段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)

Creates the UI bundle directory structure, meta XML, and optional routing/headers config. All subsequent phases require the scaffold to exist.

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 bundle目录结构、元XML文件以及可选的路由/头部配置。后续所有阶段都依赖于脚手架的存在。

Phase 2: Features (Optional)

阶段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

Installs pre-built, tested feature packages. Skip if the app requires no pre-built features. Always check for an existing feature before building from scratch. Features provide the foundation that UI components build on top of.

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组件提供基础支撑。

Phase 3: Data Access (Backend Wiring)

阶段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)

Sets up the data layer using

@salesforce/sdk-data

. GraphQL is preferred for record operations; REST for Connect, Apex, or UI API endpoints.

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。

Phase 4: UI (Frontend)

阶段4：UI开发（前端）

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

Builds the React UI. References the data layer from Phase 3 and the features from Phase 2. Must replace all boilerplate and placeholder content.

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

构建React UI。引用阶段3的数据层和阶段2的功能。必须替换所有样板代码和占位内容。

Phase 5: Integrations (Optional)

阶段5：集成开发（可选）

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

These are independent and can be executed in parallel if both are needed.

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

这些集成相互独立，若同时需要可并行执行。

Phase 6: Deployment

阶段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)

Follows the canonical 7-step deployment sequence. Must deploy metadata before fetching schema. Must assign permissions before schema fetch.

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步部署流程。必须先部署元数据再获取Schema。必须先分配权限再获取Schema。

Phase 7: Experience Site (Optional)

阶段7：体验站点（可选）

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

Creates the Digital Experience site that hosts the UI bundle. Only needed when the user wants a public-facing or authenticated site URL.

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

创建托管UI bundle的Digital Experience站点。仅当用户需要面向公众或需认证的站点URL时才需要此阶段。

Execution Workflow

执行工作流

STEP 1: Requirements Analysis & Planning

步骤1：需求分析与规划

Actions:

Parse the user's natural language request
Identify the app name and purpose
Extract pages and navigation structure
Identify data entities and Salesforce objects needed
Detect feature requirements (authentication, search, file upload, chat)
Determine if an Experience Site is needed
Identify external domains for CSP registration

Output: Build Plan

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]
- Experience Site: [yes/no, site name if applicable]

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
7. generating-experience-react-site (if site requested)

操作：

解析用户的自然语言请求
确定应用名称和用途
提取页面和导航结构
识别所需的数据实体和Salesforce对象
检测功能需求（认证、搜索、文件上传、聊天）
判断是否需要Experience Site
识别需注册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]
- Experience Site: [yes/no, site name if applicable]

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
7. generating-experience-react-site (if site requested)

STEP 2: Per-Phase Execution

步骤2：分阶段执行

Execute each phase sequentially. Complete all steps within a phase before moving to the next. For each phase:

Step	What to do	Why
1. Load skill	Invoke the skill (e.g., via the Skill tool) for this phase	Gives you the current rules, patterns, constraints, and implementation guides
2. Execute	Follow the loaded skill's workflow to generate code/config	The skill defines HOW to do the work correctly
3. Verify	Run lint and build from the UI bundle directory	Catch errors before moving to the next phase
4. Checkpoint	Confirm phase completion before proceeding	Ensures dependencies are satisfied for the next phase

Do NOT skip step 1 (loading the skill). Even if you remember the skill's content, skills evolve. Always load the current version.

Phase 1 -- Scaffolding

1. Load skill: Invoke
```
generating-ui-bundle-metadata
```
1. Execute: Run
```
sf template generate ui-bundle
```
  , install dependencies (
```
npm install
```
  ), configure meta XML, ui-bundle.json, and CSP trusted sites
1. Verify: Confirm directory structure and metadata files exist
1. Checkpoint: UI bundle scaffold is ready -- proceed to Phase 2

Phase 2 -- Features (skip if no pre-built features needed)

1. Load skill: Invoke
```
generating-ui-bundle-features
```
1. Execute: Install dependencies, search and install features, integrate example files
1. Verify: Run
```
npm run build
```
  to confirm features integrate cleanly
1. Checkpoint: Features installed -- proceed to Phase 3

Phase 3 -- Data Access (skip if no Salesforce data needed)

1. Load skill: Invoke
```
using-ui-bundle-salesforce-data
```
1. Execute: Fetch schema, look up entities, generate queries/mutations, wire into components
1. Verify: Run
```
npx eslint
```
  on files with GraphQL queries
1. Checkpoint: Data layer ready -- proceed to Phase 4

Phase 4 -- UI

1. Load skill: Invoke
```
building-ui-bundle-frontend
```
1. Execute: Build layout, pages, components, navigation. Replace all boilerplate.
1. Verify: Run lint and build -- 0 errors required
1. Checkpoint: UI complete -- proceed to Phase 5

Phase 5 -- Integrations (skip if not requested)

1. Load skill(s): Invoke
```
implementing-ui-bundle-agentforce-conversation-client
```
  (5a) and/or
```
implementing-ui-bundle-file-upload
```
  (5b). If both are needed, they are independent and can be executed in parallel.
1. Execute: Follow each skill's workflow to add the integration
1. Verify: Run lint and build
1. Checkpoint: Integrations complete -- proceed to Phase 6

Phase 6 -- Deployment

1. Load skill: Invoke
```
deploying-ui-bundle
```
1. Execute: Follow the 7-step deployment sequence (auth, build, deploy, permissions, data, schema, final build)
1. Verify: Confirm deployment succeeds and app is accessible
1. Checkpoint: App deployed -- proceed to Phase 7 if needed

Phase 7 -- Experience Site (skip if not requested)

1. Load skill: Invoke
```
generating-experience-react-site
```
1. Execute: Resolve properties, generate site metadata, deploy
1. Verify: Confirm site URL is accessible
1. Checkpoint: Site live -- build complete

按顺序执行每个阶段。完成一个阶段内的所有步骤后再进入下一阶段。每个阶段的操作如下：

步骤	操作内容	原因
1. 加载技能	调用对应阶段的技能（如通过Skill工具）	获取当前规则、模式、约束和实现指南
2. 执行	按照加载的技能工作流生成代码/配置	技能定义了正确的工作方式
3. 验证	在UI bundle目录下运行lint和构建命令	在进入下一阶段前捕获错误
4. 检查点	确认阶段完成后再继续	确保下一阶段的依赖已满足

请勿跳过步骤1（加载技能）。即使你记得技能内容，技能也会不断更新。请始终加载最新版本。

阶段1 -- 脚手架搭建

1. 加载技能：调用
```
generating-ui-bundle-metadata
```
1. 执行：运行
```
sf template generate ui-bundle
```
  ，安装依赖（
```
npm install
```
  ），配置元XML、ui-bundle.json和CSP可信站点
1. 验证：确认目录结构和元数据文件存在
1. 检查点：UI bundle脚手架已准备就绪——进入阶段2

阶段2 -- 功能开发（无预构建需求则跳过）

1. 加载技能：调用
```
generating-ui-bundle-features
```
1. 执行：安装依赖，搜索并安装功能，集成示例文件
1. 验证：运行
```
npm run build
```
  确认功能集成正常
1. 检查点：功能已安装——进入阶段3

阶段3 -- 数据访问（无需Salesforce数据则跳过）

1. 加载技能：调用
```
using-ui-bundle-salesforce-data
```
1. 执行：获取Schema，查找实体，生成查询/变更，连接到组件
1. 验证：对包含GraphQL查询的文件运行
```
npx eslint
```
1. 检查点：数据层已准备就绪——进入阶段4

阶段4 -- UI开发

1. 加载技能：调用
```
building-ui-bundle-frontend
```
1. 执行：构建布局、页面、组件、导航。替换所有样板代码。
1. 验证：运行lint和构建——要求0错误
1. 检查点：UI开发完成——进入阶段5

阶段5 -- 集成开发（无需求则跳过）

1. 加载技能：调用
```
implementing-ui-bundle-agentforce-conversation-client
```
  （5a）和/或
```
implementing-ui-bundle-file-upload
```
  （5b）。若同时需要，二者相互独立可并行执行。
1. 执行：按照每个技能的工作流添加集成
1. 验证：运行lint和构建
1. 检查点：集成完成——进入阶段6

阶段6 -- 部署

1. 加载技能：调用
```
deploying-ui-bundle
```
1. 执行：遵循7步部署流程（认证、构建、部署、权限配置、数据导入、Schema获取、最终构建）
1. 验证：确认部署成功且应用可访问
1. 检查点：应用已部署——若需要则进入阶段7

阶段7 -- 体验站点（无需求则跳过）

1. 加载技能：调用
```
generating-experience-react-site
```
1. 执行：解析属性，生成站点元数据，部署
1. 验证：确认站点URL可访问
1. 检查点：站点已上线——构建完成

STEP 3: Final Summary

步骤3：最终总结

After all phases complete, present a build summary:

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: Experience Site -- [site URL or "skipped"]

FILES GENERATED:
[list key files and their paths]

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

所有阶段完成后，展示构建总结：

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: Experience Site -- [site URL or "skipped"]

FILES GENERATED:
[list key files and their paths]

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

Validation

验证

Before presenting the build as complete, verify:

Scaffold exists: UI bundle directory with valid meta XML and ui-bundle.json
Dependencies installed:
```
node_modules/
```
exists and
```
package.json
```
has expected packages
Build passes:
```
npm run build
```
produces
```
dist/
```
with no errors
Lint passes:
```
npx eslint src/
```
reports 0 errors
No boilerplate: All placeholder text, default titles, and template content has been replaced
Navigation works:
```
appLayout.tsx
```
has real nav items matching created pages
Data layer wired: Components use
```
@salesforce/sdk-data
```
(if data access phase was executed)
CSP registered: All external domains have CSP Trusted Site metadata (if applicable)

在确认构建完成前，需验证以下内容：

脚手架存在：UI bundle目录包含有效的元XML和ui-bundle.json
依赖已安装：
```
node_modules/
```
存在且
```
package.json
```
包含预期包
构建通过：
```
npm run build
```
生成
```
dist/
```
目录且无错误
Lint通过：
```
npx eslint src/
```
报告0错误
无样板代码：所有占位文本、默认标题和模板内容已替换为应用专属内容
导航正常：
```
appLayout.tsx
```
包含与创建页面匹配的真实导航项
数据层已连接：组件使用
```
@salesforce/sdk-data
```
（若执行了数据访问阶段）
CSP已注册：所有外部域名已注册CSP可信站点元数据（若适用）

Error Handling

错误处理

Category 1: Stop and Ask User

类别1：停止并询问用户

App purpose is too vague to determine pages or data needs
User wants features that conflict (e.g., "no authentication" + "show user-specific data")
Target org is unknown and deployment is requested

应用用途过于模糊，无法确定页面或数据需求
用户想要的功能存在冲突（如「无需认证」+「显示用户专属数据」）
目标组织未知但用户要求部署

Category 2: Log Warning, Continue

类别2：记录警告，继续执行

A feature install has minor conflicts (resolve and continue)
Optional integration setup encounters non-blocking issues
Build has non-error warnings

功能安装存在轻微冲突（解决后继续）
可选集成设置遇到非阻塞问题
构建存在非错误警告

Best Practices

最佳实践

1. Always Follow Phase Order

1. 严格遵循阶段顺序

Never build UI before installing features. Never deploy before building. Dependencies are strict.

切勿在安装功能前构建UI。切勿在构建前部署。依赖关系是严格的。

2. Replace All Boilerplate

2. 替换所有样板代码

Every generated app must feel purpose-built. Replace "React App" titles, "Vite + React" placeholders, and all default content with real app-specific text and branding.

每个生成的应用都应具备专属特性。将「React App」标题、「Vite + React」占位符及所有默认内容替换为真实的应用专属文本和品牌信息。

3. Design with Intent

3. 有目的性地设计

Follow the design thinking and frontend aesthetics guidance from

building-ui-bundle-frontend

. Every app should have a clear visual direction -- not generic defaults.

遵循

building-ui-bundle-frontend

中的设计思维和前端美学指南。每个应用都应有清晰的视觉方向——而非通用默认样式。