To deploy an Experience Cloud site in Salesforce, enable the ExperienceBundle Metadata API in both orgs, retrieve the site metadata in the format matching your site framework, deploy it alongside Network and CustomSite, then publish the site in the target org. Which metadata type you need depends on how the site was built: enhanced LWR sites use DigitalExperienceBundle and DigitalExperienceConfig, non-enhanced LWR sites use ExperienceBundle, and Aura sites use ExperienceBundle or SiteDotCom.

Getting that first choice wrong is why most Experience Cloud deployments fail before they start. This guide covers prerequisites, the deployment process, the metadata that lives outside the bundle, the errors you will actually hit, and what to check once the site is live. It is written for administrators and developers working across sandbox and production environments.

What Is an ExperienceBundle in Salesforce?

ExperienceBundle is a metadata format that represents an Experience Cloud site as a set of readable JSON files instead of a single binary. Introduced in 2019, it replaced the older SiteDotCom format, which packaged the whole site into one opaque .site file that could not be diffed, merged, or partially deployed.

Retrieved locally, the bundle expands into a directory containing brandingSets, config, routes, themes, variations and views. Each change appears in a Git diff, pull requests become reviewable, and you can deploy individual pages rather than the entire site every time.

DigitalExperienceBundle is the newer equivalent for enhanced LWR sites, introduced in Winter ’23 (API version 56.0). It works alongside DigitalExperienceConfig, which holds the site label, URL path prefix and workspace type, and both must be deployed together. Like ExperienceBundle it supports partial deployment.

Prerequisites for Experience Cloud Site Deployment

Work through these before you retrieve anything. Most failed deployments trace back to one of the first two.

1. Digital Experiences enabled in both the source and target orgs.
2. Enable ExperienceBundle Metadata API switched on in Digital Experiences settings in both orgs. This is a manual step in the target org and cannot reliably be included in the same package as the bundle itself. If retrieval returns nothing, check this first.
3. Salesforce CLI installed, with both orgs authorised.
4. Deployment permissions on the target org, including Modify All Data or an equivalent, and access to Experience Builder for the publish step.
5. Domains configured in the target org. Mismatched domain settings between source and target produce deployment errors.
6. A backup of the current target site taken before you deploy, so you have something to restore to.

How to Deploy an Experience Cloud Site in Salesforce

The process below moves a tested site from a sandbox into production. Steps 1 to 5 expand on each stage.

7. Identify the site framework and retrieve the matching bundle type.
8. Apply governance controls before the change enters the pipeline.
9. Build, test and validate against the target org.
10. Deploy to production.
11. Verify, publish and monitor.

1. Identify Your Experience Cloud Site and Bundle Type

Check which template your site uses before anything else, because it determines the metadata type and the retrieve command.

With the type identified, retrieve the site metadata:

# Aura or non-enhanced LWR sites
sf project retrieve start \
  --metadata "ExperienceBundle:Customer_Portal" \
  --metadata "Network:Customer_Portal" \
  --metadata "CustomSite:Customer_Portal"

# Enhanced LWR sites (Winter '23, API 56.0+)
sf project retrieve start \
  --metadata "DigitalExperienceBundle:Customer_Portal" \
  --metadata "DigitalExperienceConfig:Customer_Portal" \
  --metadata "Network:Customer_Portal" \
  --metadata "CustomSite:Customer_Portal"

Retrieve Network and CustomSite alongside the bundle in every case. Network holds the site’s administration settings, including page overrides, email and membership configuration. CustomSite holds the domain and page settings, including indexPage, siteAdmin and URL definitions. A bundle deployed without them will not produce a working site.

Scope the package deliberately. Deploying an entire project directory sweeps up every unrelated change sitting in it. Use a controlled manifest instead:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Customer_Portal</members>
        <name>ExperienceBundle</name>
    </types>
    <types>
        <members>Customer_Portal</members>
        <name>Network</name>
    </types>
    <types>
        <members>Customer_Portal</members>
        <name>CustomSite</name>
    </types>
    <types>
        <members>Customer_Portal_Main_Nav</members>
        <name>NavigationMenu</name>
    </types>
    <version>64.0</version>
</Package>

One constraint worth knowing: do not include SiteDotCom metadata in the same package as an ExperienceBundle. Mixing the two formats is a common source of validation errors.

2. Integrate Governance Throughout the Pipeline

Readable JSON makes changes easy to see. Proving who changed what, why, and under which approval is a separate problem, and in regulated environments auditors expect controls across the whole pipeline rather than a single pre-commit check.

Pre-Commit Controls

• Run static analysis to detect secrets or personal data embedded in JSON.
• Validate JSON syntax so only the attributes you intended have changed.
• Reference ticket IDs in commit messages and branch names for a traceable trail.
• Capture a baseline snapshot for rollback.

Continuous Controls

• Enforce role-based access control on branch creation, pull request approval and production deployment.
• Maintain immutable audit logs with accurate timestamps.
• Require multiple reviewers for branding, navigation and access-related changes, which are the ones users notice immediately.

3. Build, Test, and Validate

Validation against the target org is the step that catches missing dependencies before they become a failed production deployment. For teams under SOX, HIPAA or FedRAMP obligations, it doubles as the evidence that checks ran before release.

Build & Test

# 1. Preview what will change and what is missing
sf project deploy preview \
  --manifest manifest/package.xml \
  --target-org Production

# 2. Validate against the target without committing
sf project deploy validate \
  --manifest manifest/package.xml \
  --test-level RunLocalTests \
  --target-org Production

# 3. Deploy once validation passes
sf project deploy start \
  --manifest manifest/package.xml \
  --test-level RunLocalTests \
  --target-org Production

# 4. Publish the site in Experience Builder to make it live

Preview surfaces what will change and what is missing. Validate runs the deployment against the target without committing it, which is where dependency and profile mismatches appear. Apex test coverage must clear Salesforce’s 75% threshold for a production deployment.

Compliance Validation

• Static security scans for hard-coded credentials or insecure attributes.
• Dependency verification, confirming every referenced component exists in the target.
• Salesforce Security Health Check scans, retained as evidence of readiness.

4. Deploy to Production with Zero Downtime

Production deployment should ship the artifact you already validated, not a freshly assembled one. Deploy the same package, in a low-traffic window, with the rollback path agreed in advance.

A note on “zero downtime”: a metadata deployment does not take an Experience Cloud site offline, but the site continues serving the previously published version until you publish. That gap is useful. It means you can deploy during business hours and publish deliberately once verification passes, rather than treating deployment and go-live as one event.

5. Verify, Publish, and Monitor the Site

Deploying does not make changes live. You have to publish the site in the target org before anything reaches users, and this is the single most commonly missed step in the whole process.

Publish the site

1. Open Experience Builder in the target org and select the deployed site.
2. Review the pages, navigation and theme in the builder preview before going live.
3. Click Publish. Each publish replaces the live version with the current one.
4. Confirm the site status. A site left in preview or maintenance status stays unavailable to its audience regardless of a successful deployment.

Verification Checklist

• Visual QA across pages, themes and navigation, on desktop and mobile.
• Functional scripts covering the key user journeys.
• Audit log and event monitoring review to confirm no unexpected errors.
• Stakeholder walkthrough with documented sign-off.

On rollback: Salesforce provides no native one-click rollback for a site deployment. Your realistic options are republishing the previous version from Experience Builder, redeploying the previous bundle from source control, or restoring from a backup taken before the deployment. Decide which of these you are relying on before you deploy, not after.

Required Metadata for an Experience Cloud Deployment

The bundle does not contain everything the site depends on. These components live outside it and have to travel with the deployment or already exist in the target:

• Network and CustomSite: always required alongside the bundle.
• Navigation menus: referenced by API name. A menu missing from the target produces a deployment error rather than an empty menu.
• Static resources and content assets: images, logos and files referenced by pages and branding.
• Apex classes and Visualforce pages: including the CommunitiesLanding page and its controller on Aura sites.
• Profiles and permission sets: guest user access in particular, which governs what unauthenticated visitors can see.
• Flows and custom components: anything embedded in a page must exist in the target before the page referencing it deploys.

Common Experience Cloud Deployment Errors

“The currentThemeId property is null or points to a non-theme component.” Theme IDs differ between orgs. Update the theme selection in Experience Builder in the target, save, and publish.

“The recordId property of component [id] references an object with the ID value [id].” A component points at a record ID that does not exist in the target, which typically happens after a sandbox refresh. Update the reference to a valid ID in the destination org.

“Implement forceCommunity:availableForAllPageTypes for the Aura component [name].” A custom Aura component is not marked as available for Experience Builder pages. Add the interface to the component and redeploy it before the bundle.

Site name mismatch. A site created in an org gets the API name SiteName1, but renaming it later changes the convention to SiteName_C. If source and target were named at different times, the names no longer match and deployment fails. Rename the site in both orgs so they match; if they already match, rename temporarily and back to force it.

Nothing retrieved at all. Either the ExperienceBundle Metadata API setting is off, or you are querying the wrong metadata type for your site framework. Check both before troubleshooting anything else.

Experience Cloud Deployment Best Practices

• Back up the target site before every deployment. It is the only rollback option that survives a bad publish.
• Deploy dependencies first, in their own package: Apex, components, static resources, then the bundle.
• Keep source and target on comparable API versions. Version drift between orgs is a recurring cause of unexplained failures.
• Scope every package. Never deploy a whole project directory to production.
• Treat site changes as releases, not configuration. Version control, review and approval apply here as they do to code.

Post-Deployment Testing Checklist

• Guest user: open the site in a private browser window with no session. Confirm public pages render and that nothing is exposed that should not be.
• Authenticated user: log in as a member of each audience and confirm the pages, records and actions they should see.
• Login and registration: run through self-registration, login, and password reset end to end.
• Navigation and themes: check every menu item resolves, and that branding matches the source.
• Embedded flows and integrations: trigger each one rather than assuming deployment implies function.
• Mobile: confirm layouts hold on a real device, not just a resized browser.

Manage Experience Cloud Deployments with Flosum

Experience Cloud deployments involve many interdependent components, a mandatory publish step, and no native rollback, which makes them a governance problem as much as a technical one. Flosum is an end-to-end enterprise DevSecOps platform purpose-built for Salesforce, keeping metadata inside the platform while providing automated pipelines, dependency and conflict detection, differential deployments, native audit trails with role-based approvals, and snapshot-based rollback when a release needs reversing.

For teams managing sites across several orgs, that combination turns Experience Cloud releases into a repeatable, auditable process. Request a demo to see the workflow end to end.

Frequently Asked Questions (FAQ)