Generating Ui Bundle Site

Digital Experience Site for React UI Bundles

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.

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.

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.

Generation Workflow

Step 1: Resolve All Required Properties

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

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:

The DigitalExperience directory contains only _meta.json and content.json. Do not create any directories other than sfdc_cms__site inside the bundle.

Step 3: Populate All Metadata Fields

Use the default templates in the docs below. Values in {braces} are resolved property references — substitute them with the actual values from Step 1.

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

Execution Note for Step 3: Load and use the docs

• 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.

Step 4: Do Not Modify Non-Templated Properties

Do not modify any default property values for Network, CustomSite, DigitalExperience, DigitalExperienceConfig, or DigitalExperienceBundle metadata that are not expressed as variables wrapped in {braces}.

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:

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

Common Workflows

Updating Experience Site URLs

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)

Configure Metadata: CustomSite

Purpose

This configuration file creates a net-new, default CustomSite metadata record for a Digital Experience React Site. It is not intended to edit or modify an existing CustomSite record. Use this template only when provisioning a brand-new React site.

File Location

sites/{siteName}.site-meta.xml

Default Template

<?xml version="1.0" encoding="UTF-8"?>
<CustomSite xmlns="http://soap.sforce.com/2006/04/metadata">
    <active>true</active>
    <allowGuestPaymentsApi>false</allowGuestPaymentsApi>
    <allowHomePage>false</allowHomePage>
    <allowStandardAnswersPages>false</allowStandardAnswersPages>
    <allowStandardIdeasPages>false</allowStandardIdeasPages>
    <allowStandardLookups>false</allowStandardLookups>
    <allowStandardPortalPages>true</allowStandardPortalPages>
    <allowStandardSearch>false</allowStandardSearch>
    <authorizationRequiredPage>CommunitiesLogin</authorizationRequiredPage>
    <bandwidthExceededPage>BandwidthExceeded</bandwidthExceededPage>
    <browserXssProtection>true</browserXssProtection>
    <cachePublicVisualforcePagesInProxyServers>true</cachePublicVisualforcePagesInProxyServers>
    <clickjackProtectionLevel>SameOriginOnly</clickjackProtectionLevel>
    <contentSniffingProtection>true</contentSniffingProtection>
    <enableAuraRequests>true</enableAuraRequests>
    <fileNotFoundPage>FileNotFound</fileNotFoundPage>
    <genericErrorPage>Exception</genericErrorPage>
    <inMaintenancePage>InMaintenance</inMaintenancePage>
    <indexPage>CommunitiesLanding</indexPage>
    <masterLabel>{siteName}</masterLabel>
    <redirectToCustomDomain>false</redirectToCustomDomain>
    <referrerPolicyOriginWhenCrossOrigin>true</referrerPolicyOriginWhenCrossOrigin>
    <selfRegPage>CommunitiesSelfReg</selfRegPage>
    <siteType>ChatterNetwork</siteType>
    <urlPathPrefix>{siteUrlPathPrefix}vforcesite</urlPathPrefix>
</CustomSite>

Configure Metadata: DigitalExperienceBundle

Purpose

This configuration file creates a net-new, default DigitalExperienceBundle metadata record for a Digital Experience React Site. It is not intended to edit or modify an existing DigitalExperienceBundle record. Use this template only when provisioning a brand-new React site.

File Location

digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml

Default Template

<?xml version="1.0" encoding="UTF-8"?>
<DigitalExperienceBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>{siteName}1</label>
</DigitalExperienceBundle>

Configure Metadata: DigitalExperienceConfig

Purpose

This configuration file creates a net-new, default DigitalExperienceConfig metadata record for a Digital Experience React Site. It is not intended to edit or modify an existing DigitalExperienceConfig record. Use this template only when provisioning a brand-new React site.

File Location

digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml

Default Template

<?xml version="1.0" encoding="UTF-8"?>
<DigitalExperienceConfig xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>{siteName}</label>
    <site>
        <urlPathPrefix>{siteUrlPathPrefix}</urlPathPrefix>
    </site>
    <space>site/{siteName}1</space>
</DigitalExperienceConfig>

Configure Metadata: DigitalExperience (sfdc_cms__site)

Purpose

These configuration files create net-new, default DigitalExperience content records (sfdc_cms__site type) for a Digital Experience React Site. They are not intended to edit or modify existing DigitalExperience content. Use these templates only when provisioning a brand-new React site.

The appContainer: true field in content.json is what makes this a React site rather than a standard LWR site. The appSpace field should be left empty if the UIBundle metadata record does not already exist. When the UIBundle exists, populate the appSpace value following the format {namespace}__{developerName} to match the deployed UIBundle metadata record.

File Location

The DigitalExperience directory contains only _meta.json and content.json. Do not create any directories other than sfdc_cms__site inside the bundle.

digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/_meta.json
digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/content.json

Default Templates

_meta.json

{
  "apiName": "{siteName}1",
  "path": "",
  "type": "sfdc_cms__site"
}

content.json

{
  "type": "sfdc_cms__site",
  "title": "{siteName}",
  "urlName": "{siteUrlPathPrefix}",
  "contentBody": {
    "authenticationType": "AUTHENTICATED_WITH_PUBLIC_ACCESS_ENABLED",
    "appContainer": true,
    "appSpace": ""
  }
}

Note: Leave appSpace empty ("") if the UIBundle does not exist. If the UIBundle metadata record is already deployed, populate it with "{appNamespace}__{appDevName}".

Configure Metadata: Network

Purpose

This configuration file creates a net-new, default Network metadata record for a Digital Experience React Site. It is not intended to edit or modify an existing Network record. Use this template only when provisioning a brand-new React site.

File Location

networks/{siteName}.network-meta.xml

Default Template

<?xml version="1.0" encoding="UTF-8"?>
<Network xmlns="http://soap.sforce.com/2006/04/metadata">
    <allowInternalUserLogin>false</allowInternalUserLogin>
    <allowMembersToFlag>false</allowMembersToFlag>
    <changePasswordTemplate>unfiled$public/CommunityChangePasswordEmailTemplate</changePasswordTemplate>
    <disableReputationRecordConversations>true</disableReputationRecordConversations>
    <emailSenderAddress>admin@company.com</emailSenderAddress>
    <emailSenderName>{siteName}</emailSenderName>
    <embeddedLoginEnabled>false</embeddedLoginEnabled>
    <enableApexCDNCaching>true</enableApexCDNCaching>
    <enableCustomVFErrorPageOverrides>false</enableCustomVFErrorPageOverrides>
    <enableDirectMessages>true</enableDirectMessages>
    <enableExpFriendlyUrlsAsDefault>false</enableExpFriendlyUrlsAsDefault>
    <enableExperienceBundleBasedSnaOverrideEnabled>true</enableExperienceBundleBasedSnaOverrideEnabled>
    <enableGuestChatter>{enableGuestAccess}</enableGuestChatter>
    <enableGuestFileAccess>false</enableGuestFileAccess>
    <enableGuestMemberVisibility>false</enableGuestMemberVisibility>
    <enableImageOptimizationCDN>true</enableImageOptimizationCDN>
    <enableInvitation>false</enableInvitation>
    <enableKnowledgeable>false</enableKnowledgeable>
    <enableLWRExperienceConnectedApp>false</enableLWRExperienceConnectedApp>
    <enableMemberVisibility>false</enableMemberVisibility>
    <enableNicknameDisplay>true</enableNicknameDisplay>
    <enablePrivateMessages>false</enablePrivateMessages>
    <enableReputation>false</enableReputation>
    <enableShowAllNetworkSettings>false</enableShowAllNetworkSettings>
    <enableSiteAsContainer>true</enableSiteAsContainer>
    <enableTalkingAboutStats>true</enableTalkingAboutStats>
    <enableTopicAssignmentRules>true</enableTopicAssignmentRules>
    <enableTopicSuggestions>false</enableTopicSuggestions>
    <enableUpDownVote>false</enableUpDownVote>
    <forgotPasswordTemplate>unfiled$public/CommunityForgotPasswordEmailTemplate</forgotPasswordTemplate>
    <gatherCustomerSentimentData>false</gatherCustomerSentimentData>
    <headlessForgotPasswordTemplate>unfiled$public/CommunityHeadlessForgotPasswordTemplate</headlessForgotPasswordTemplate>
    <headlessRegistrationTemplate>unfiled$public/CommunityHeadlessRegistrationTemplate</headlessRegistrationTemplate>
    <networkMemberGroups>
        <profile>admin</profile>
    </networkMemberGroups>
    <networkPageOverrides>
        <changePasswordPageOverrideSetting>Standard</changePasswordPageOverrideSetting>
        <forgotPasswordPageOverrideSetting>Designer</forgotPasswordPageOverrideSetting>
        <homePageOverrideSetting>Designer</homePageOverrideSetting>
        <loginPageOverrideSetting>Designer</loginPageOverrideSetting>
        <selfRegProfilePageOverrideSetting>Designer</selfRegProfilePageOverrideSetting>
    </networkPageOverrides>
    <newSenderAddress>admin@company.com</newSenderAddress>
    <picassoSite>{siteName}1</picassoSite>
    <selfRegistration>false</selfRegistration>
    <sendWelcomeEmail>true</sendWelcomeEmail>
    <site>{siteName}</site>
    <siteArchiveStatus>NotArchived</siteArchiveStatus>
    <status>Live</status>
    <tabs>
        <defaultTab>home</defaultTab>
        <standardTab>Chatter</standardTab>
    </tabs>
    <urlPathPrefix>{siteUrlPathPrefix}vforcesite</urlPathPrefix>
    <welcomeTemplate>unfiled$public/CommunityWelcomeEmailTemplate</welcomeTemplate>
</Network>

Updating Experience Site URLs

Experience sites have a three-component architecture with two distinct URL patterns. Understanding this structure is critical when updating site URLs.

Architecture Overview

Every Salesforce Experience Site consists of three components:

1. Network (metadata: Network) - Network configuration 2. ChatterNetwork Site (metadata: CustomSite) - Legacy site and proxy core site services 3. ChatterNetworkPicasso Site (metadata: DigitalExperienceConfig + DigitalExperienceBundle) - Customer-facing pages and content

URL Pattern

These three components use two different URLs:

• Primary URL (ChatterNetworkPicasso): Used for customer-facing pages
• Defined in: DigitalExperienceConfig → <urlPathPrefix>
• Example: mysite

• Secondary URL (Network + CustomSite): Used for legacy authentication endpoints and other services
• Defined in: Network → <urlPathPrefix> AND CustomSite → <urlPathPrefix>
• Example: mysitevforcesite
• Must be synchronized - both files must have identical values

By default, Salesforce differentiates these URLs by appending vforcesite suffix to the Network/CustomSite URL.

URL Update Workflow

When updating site URLs, follow this workflow:

Step 1: Discover All URL References

Search for all occurrences of urlPathPrefix across the project metadata files.

For agents: Use the search_files tool with these parameters:

• path: force-app/main/default
• regex: urlPathPrefix
• file_pattern: *.xml

For humans: Use your IDE's search functionality or command line tools:

# Using grep
grep -r "urlPathPrefix" force-app/main/default --include="*.xml"

# Using VS Code: Ctrl+Shift+F (Windows/Linux) or Cmd+Shift+F (Mac)
# Search for: urlPathPrefix
# Files to include: *.xml

Step 2: Identify URL Groups

Determine which files belong to which URL group:

• Primary URL Group: DigitalExperienceConfig
• Secondary URL Group: Network AND CustomSite

Step 3: Update URLs Consistently

Update the <urlPathPrefix> value in each file:

• DigitalExperienceConfig: Update to new primary URL
• Network: Update to new secondary URL (typically primary URL + vforcesite)
• CustomSite: Update to same value as Network (must be synchronized)

Step 4: Validate Naming Convention

Ensure URL values follow best practices:

• Use lowercase letters only
• Avoid special characters except hyphens where appropriate
• Keep URLs concise and meaningful

Step 5: Verify Consistency

Before deploying, confirm:

• [ ] Primary URL in DigitalExperienceConfig is set correctly
• [ ] Secondary URL in Network matches CustomSite exactly
• [ ] URLs are properly differentiated (typically via suffix)
• [ ] All URL values follow naming conventions

Example URL Configuration

ChatterNetworkPicasso Site (Primary):
  DigitalExperienceConfig: <urlPathPrefix>bestsupport</urlPathPrefix>

Network + ChatterNetwork Site (Secondary):
  Network:    <urlPathPrefix>bestsupportvforcesite</urlPathPrefix>
  CustomSite: <urlPathPrefix>bestsupportvforcesite</urlPathPrefix>

Common Pitfalls to Avoid

❌ Don't update only one or two files - all three must be updated ❌ Don't use different values in Network and CustomSite ❌ Don't use the same URL for both Primary and Secondary groups ❌ Don't skip the discovery step with search_files ✅ Do use search_files to find all occurrences first ✅ Do maintain URL differentiation between the two groups ✅ Do follow lowercase naming conventions