generating-ui-bundle-site

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Digital Experience Site for React UI Bundles

用于托管React UI包的Salesforce Digital Experience Site

Create and configure Digital Experience Sites that host React UI bundles on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the

sfdc_cms__site

content type — so a React app can be served from Salesforce.

React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (

appContainer: true

) that delegates rendering to the React UI bundle referenced by

appSpace

在Salesforce上创建并配置用于托管React UI包的Digital Experience Site。此技能会生成所需的最小站点基础设施——Network、CustomSite、DigitalExperienceConfig、DigitalExperienceBundle以及

sfdc_cms__site

内容类型——从而让React应用可以通过Salesforce提供服务。

React站点与标准LWR站点不同：它们不需要路由、视图、主题布局或品牌集。该站点作为一个轻量容器（

appContainer: true

），将渲染任务委托给

appSpace

引用的React UI包。

Required Properties

必填属性

Resolve all five properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found.

Property	Format	How to Resolve
siteName	`UpperCamelCase` (e.g., `MyCommunity` )	Ask user or derive from context
siteUrlPathPrefix	`All lowercase` (e.g., `mycommunity` )	User-provided, or convert siteName to all lowercase with alphanumeric characters only
appNamespace	String	`namespace` in `sfdx-project.json` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → default `c`
appDevName	String	`UIBundle` metadata in the project → `sf data query -q "SELECT DeveloperName FROM UIBundle" --target-org ${usernameOrAlias}` → default to siteName
enableGuestAccess	Boolean	Ask user whether unauthenticated guest users can access site APIs → default `false`

The

appNamespace

and

appDevName

properties connect the site to the correct React application. Getting these wrong means the site deploys but shows a blank page, so take care to resolve them from real project data.

在生成任何元数据之前，需确定所有五个属性的值。每个属性都有一个备选优先级——按顺序尝试每个选项，直到找到有效值。

属性	格式	确定方式
siteName	`大驼峰命名法` （例如： `MyCommunity` ）	询问用户或从上下文推导
siteUrlPathPrefix	`全小写` （例如： `mycommunity` ）	用户提供，或将siteName转换为仅含字母数字的全小写形式
appNamespace	字符串	`sfdx-project.json` 中的 `namespace` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → 默认值 `c`
appDevName	字符串	项目中的 `UIBundle` 元数据 → `sf data query -q "SELECT DeveloperName FROM UIBundle" --target-org ${usernameOrAlias}` → 默认值为siteName
enableGuestAccess	布尔值	询问用户未认证访客是否可以访问站点API → 默认值 `false`

appNamespace

和

appDevName

属性用于将站点与正确的React应用关联。如果这两个值错误，站点虽然可以部署，但会显示空白页面，因此务必从真实项目数据中确定这些值。

Generation Workflow

生成流程

Step 1: Resolve All Required Properties

步骤1：确定所有必填属性

Determine values for all five properties before constructing anything. Use the resolution strategies in the table above, falling through each option until a value is found.

在构建任何内容之前，先确定所有五个属性的值。使用上表中的确定策略，按顺序尝试每个选项，直到找到有效值。

Step 2: Create the Project Structure

步骤2：创建项目结构

Use available Salesforce metadata schema and field context for

Network

CustomSite

DigitalExperienceConfig

, and

DigitalExperienceBundle

to ensure each file uses valid structure.

Create any files and directories that don't already exist, using these paths:

Metadata Type	Path
Network	`networks/{siteName}.network-meta.xml`
CustomSite	`sites/{siteName}.site-meta.xml`
DigitalExperienceConfig	`digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml`
DigitalExperienceBundle	`digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml`
DigitalExperience (sfdc_cms__site)	`digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/*`

The DigitalExperience directory contains only

_meta.json

and

content.json

. Do not create any directories other than

sfdc_cms__site

inside the bundle.

使用Salesforce元数据架构和

Network

、

CustomSite

、

DigitalExperienceConfig

、

DigitalExperienceBundle

的字段上下文，确保每个文件使用有效的结构。

创建所有不存在的文件和目录，使用以下路径：

元数据类型	路径
Network	`networks/{siteName}.network-meta.xml`
CustomSite	`sites/{siteName}.site-meta.xml`
DigitalExperienceConfig	`digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml`
DigitalExperienceBundle	`digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml`
DigitalExperience (sfdc_cms__site)	`digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/*`

DigitalExperience目录仅包含

_meta.json

和

content.json

。不要在bundle内创建

sfdc_cms__site

之外的任何目录。

Step 3: Populate All Metadata Fields

步骤3：填充所有元数据字段

Use the default templates in the docs below. Values in

{braces}

are resolved property references — substitute them with the actual values from Step 1.

Metadata Type	Template Reference
Network	configure-metadata-network.md
CustomSite	configure-metadata-custom-site.md
DigitalExperienceConfig	configure-metadata-digital-experience-config.md
DigitalExperienceBundle	configure-metadata-digital-experience-bundle.md
DigitalExperience (sfdc_cms__site)	configure-metadata-digital-experience.md

For URL updates, see update-site-urls.md.

使用下方文档中的默认模板。

{}

中的值是已确定的属性引用——用步骤1中的实际值替换它们。

元数据类型	模板参考
Network	configure-metadata-network.md
CustomSite	configure-metadata-custom-site.md
DigitalExperienceConfig	configure-metadata-digital-experience-config.md
DigitalExperienceBundle	configure-metadata-digital-experience-bundle.md
DigitalExperience (sfdc_cms__site)	configure-metadata-digital-experience.md

有关URL更新，请参阅update-site-urls.md。

Execution Note for Step 3: Load and use the docs

步骤3执行说明：加载并使用文档

Agents MUST read the full contents of each docs/*.md file referenced in Step 3 before attempting to populate metadata fields.
Use your platform's file-read tool (for example,
```
read_file
```
) to load these files in full, then perform placeholder substitution for values in
```
{braces}
```
using the resolved properties from Step 1.

Files to load:

```
docs/configure-metadata-network.md
```
```
docs/configure-metadata-custom-site.md
```

docs/configure-metadata-digital-experience-config.md

docs/configure-metadata-digital-experience-bundle.md

docs/configure-metadata-digital-experience.md

Read entire file contents, replace placeholders (e.g.
```
{siteName}
```
) with the resolved values, then use the expanded templates to populate the metadata XML/JSON content.

Agent必须在尝试填充元数据字段之前，完整阅读步骤3中引用的每个docs/*.md文件的内容。
使用平台的文件读取工具（例如
```
read_file
```
）完整加载这些文件，然后使用步骤1中确定的属性替换
```
{}
```
中的占位符。

需要加载的文件：

```
docs/configure-metadata-network.md
```
```
docs/configure-metadata-custom-site.md
```

docs/configure-metadata-digital-experience-config.md

docs/configure-metadata-digital-experience-bundle.md

docs/configure-metadata-digital-experience.md

读取完整文件内容，替换占位符（例如
```
{siteName}
```
）为确定的值，然后使用展开后的模板填充元数据XML/JSON内容。

Step 4: Do Not Modify Non-Templated Properties

步骤4：不要修改非模板化属性

Do not modify any default property values for

Network

CustomSite

DigitalExperience

DigitalExperienceConfig

, or

DigitalExperienceBundle

metadata that are not expressed as variables wrapped in

{braces}

不要修改

Network

、

CustomSite

、

DigitalExperience

、

DigitalExperienceConfig

或

DigitalExperienceBundle

元数据中所有未用

{}

包裹的默认属性值。

Verification Checklist

验证清单

Before deploying, confirm:

All five required properties are resolved
All metadata directories and files exist per the project structure
All metadata fields match the Step 3 templates with
```
{braces}
```
substituted only; no other default property values were added or changed
```
appSpace
```
in
```
content.json
```
matches an existing
```
UIBundle
```
metadata record
Deployment validates successfully:

bash

sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}

部署前，请确认：

所有五个必填属性已确定
所有元数据目录和文件均按项目结构存在
所有元数据字段与步骤3的模板匹配，仅替换
```
{}
```
中的占位符；未添加或修改其他默认属性值
```
content.json
```
中的
```
appSpace
```
与现有
```
UIBundle
```
元数据记录匹配
部署验证成功：

bash

sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}

Common Workflows

常见流程

Updating Experience Site URLs

更新体验站点URL

Use when user wants to update or change site URLs (urlPathPrefix).

Steps:

Read update-site-urls.md to understand the three-component architecture and URL update workflow
Follow the step-by-step workflow in the doc to update URLs consistently across all three components (DigitalExperienceConfig, Network, CustomSite)

适用场景：用户想要更新或修改站点URL（urlPathPrefix）。

步骤：

阅读update-site-urls.md，了解三组件架构和URL更新流程
按照文档中的分步流程，在所有三个组件（DigitalExperienceConfig、Network、CustomSite）中一致地更新URL