How to deploy individual components of your Salesforce Digital Experience

Claudia McPhail & Ahtif Anwar on

Share with


Many teams now use Digital Experiences, Salesforce’s powerful platform for building sites, apps, and portals on Experience Cloud. While creating and customizing sites has never been easier, Digital Experiences can be difficult to deploy. But help is on hand! Gearset’s intelligent comparison and deployment engine not only provides an easy way to deploy your Salesforce metadata, it’s the only solution that enables you to publish individual components of your Digital Experience, such as single pages or branding updates.

Illustration of building Digital Experiences

From Communities to Digital Experiences

Digital Experiences are what used to be known as Communities until being rebranded in Spring ’21. Many admins and developers still refer to them as Communities, but we’ll stick to ‘Digital Experiences’ in the rest of this post.

There are two metadata types that can be used to represent the core configuration of Digital Experiences. Either type can be used to deploy your site, but there are significant differences between them.

The SiteDotCom metadata type has been around for longer but is still supported. It represents your Digital Experience as a single .site file containing a binary blob, and this means the SiteDotCom type has a few key drawbacks:

  • The .site file can’t be read by humans.
  • If multiple people each make their own changes to the Digital Experience, there’s no way to merge those changes together.
  • The metadata can’t be decomposed for deployments of individual components, e.g. of a single page. You have to deploy the whole Digital Experience every time you make a change.

In short, SiteDotCom makes development and deployments a headache because the binary blob isn’t exactly user-friendly. This is what it looks like when I try to open the .site file that represents one of my Experience Cloud sites.

The binary blob of a .site file

In 2019, Salesforce released the ExperienceBundle metadata type, which provides a better alternative to SiteDotCom. Rather than one .site file, ExperienceBundle gives you numerous .json files within a sensible folder structure. As these files are in plain text, your Digital Experience metadata is now human-readable. And if you’re using version control, having several separate files makes it less likely that developers will update the same file and trigger a merge conflict. Here’s that same Experience Cloud site, now represented with human-readable .json files in a sensible folder structure.

A set of .json files in VSCode

What about the inability to deploy individual changes with SiteDotCom? Switching to ExperienceBundles doesn’t automatically make this possible. But with Gearset you can, as set out below.

Gearset is unique in the way that it downloads and compares the metadata in your source and target before each deployment. During this process, Gearset’s proprietary logic cleverly processes various metadata types, especially tricky ones such as profiles and permissions. In the case of ExperienceBundles, Gearset decomposes the metadata so you can select individual components you want to deploy, then recomposes your selections as bundles that can be deployed over the Metadata API.

The value of partial publishing

Why is it so useful to be able to deploy individual changes to your Digital Experience? Quite simply, there are so many elements to Digital Experiences that it’s a pain to deploy the entire site for each adjustment. Consider how much customization is possible using Experience Builder, which gives you fine-grained control over every aspect of the site.

Experience Builder

All of these Digital Experience customizations are described in your metadata, and if you’ve switched to using the ExperienceBundle metadata type, you’ll have an ExperienceBundle folder with the following subfolders, each containing multiple .json files of various types:

ExperienceBundle folderFiles
configsite_name.json, languages.json, loginAppPage.json

Imagine you’ve made changes to just one page of your Experience Cloud site, or you’ve been working in VSCode on particular .json files in your ExperienceBundle folder. The quickest and best way to test or release your work is to deploy only what you’ve changed to the relevant environment in your pipeline. Deploying the entire site or the entire folder structure is unnecessary.

Only deploying the files you’ve changed also helps to avoid accidentally overwriting changes made by your teammates, whether you’re deploying to version control or straight to a Salesforce org. Here as elsewhere in your workflow, Salesforce DevOps works best when you’re promoting small but logical slices of work along your release pipeline, shipping small and often to your end users.

How to deploy individual ExperienceBundle components

If your Digital Experience is already in the target environment for your deployment, and you just want to deploy the individual components that you’ve changed in the source environment, you can do this straight away using Gearset, as described below. If your Digital Experience doesn’t already exist in your target environment, you can deploy the whole site using Gearset in a series of deployments.

1. Begin with all things Apex

First, you should deploy any new Apex classes and Apex pages created by the Digital Experience in your source. You’ll need your Apex in the target to be able to deploy the site’s metadata, which depends on that code.

2. Deploy your site

To deploy the site itself, make sure you select the relevant metadata types in Gearset’s metadata filter:

  • Experience bundle
  • Network (Communities)
  • Custom site (Communities)
  • Permission sets - if these have been changed.

Teams that don’t use Gearset find their Digital Experience deployments often fail because the site references a user that doesn’t exist in the target environment. Gearset solves this problem for you with one of its proprietary problem analyzers, which identifies the missing user and flags up the problem for you with a suggested fix. Expect to see a suggestion like the one shown below when you use Gearset to deploy a new or changed Digital Experience. Accepting this fix allows Gearset to change the user referenced by your site, switching it to the equivalent user in your target.

One of Gearset's proprietary problem analyzers

3. Deploy individual components

Once your Experience Cloud site is in the target environment, you can deploy any individual changes that you make in the source environment. When you compare your orgs using Gearset, you’ll see the entire ExperienceBundle on one line, such as the Knowledge_Base bundle in the example shown below. But Gearset also breaks down your ExperienceBundle into its constituent components, which are all of the individual .json files containing your metadata.

You can view individual .json files, see the exact differences between source and target, and select which files you’d like to include in your deployment package, rather than deploying everything. In this example, we’ve selected the file that determines the branding of our site’s help center - you can see that changes have been made to the colors and font.

Gearset's compare and deploy tool

Deploying a single page of your Digital Experience is a common use case. What end users see as a page on the site is represented in your ExperienceBundle metadata as a .json file in the ‘views’ folder. In the comparison grid, look for the Experience bundle component that has the relevant name: {Digital_Experience_Name}/views/{pageName}.json. In this example, we’ve selected the .json file that represents a homepage variation of our site for anyone based in Chicago.

Gearset's compare and deploy tool

For other individual changes, you’ll need to include the relevant metadata types in your comparison and deployment. If you’re wanting to deploy the navigational sections of your site, select the Managed topics (Community) metadata type. If you have images, you’ll need to include the Content asset type.

Try deploying your Digital Experiences!

If deploying Digital Experiences (or Communities if that’s how you still think of them!) is something you wish was easier, try using Gearset. No other deployment tool has the capability to deploy such fine-grained changes to your sites, so it’s well worth seeing if it makes all the difference to your development and release process. Let us know how you get on! Gearset also catches missing dependencies and offers full or partial rollback, plus many more essentials for ensuring your deployment success on Salesforce.

Ready to get started with Gearset?