Salesforce Lightning communities are a great way to drive collaboration between your team members and your customers. That said, collaborative development of communities has always been difficult. Luckily, the new ExperienceBundle metadata type is here to change that!

The problem with the SiteDotCom type

The SiteDotCom metadata type allows you to deploy your community from one org to another, but it stores your community's branding, config, routes, themes, and views as a binary .site file. This means that you can't compare the differences between two orgs because binary files aren't human-readable.

Another big drawback of the binary format is that you can't merge changes. So if two developers are working on the same community at the same time, there's a risk they'll overwrite each other's changes when they deploy.

How the ExperienceBundle type helps

The ExperienceBundle type breaks down the metadata into multiple plain text files - previously, this was all lumped together in the .site file. As plain text is human-readable, you can compare two communities or two versions of the same community. And now developers can merge their changes!

Even better, there's now a good chance that independent changes won't touch the same files. Previously, if you added two separate branding sets, these would both go in the same .site file. In the ExperienceBundle format, the branding sets are separate files in the brandingSets directory. This is great if you're using source control because Git will be able to merge the two commits for you automatically.

Human-readable is also human-editable: make quick changes locally in your favorite IDE and deploy them to your scratch org - no need to fire up Community Builder every time!

Make sure you enable the feature!

You can only retrieve/deploy an ExperienceBundle if you enable the feature in Communities Settings: search for Communities Settings in Quick Find, choose Communities Settings, and make sure Enable ExperienceBundle Metadata API is checked under Community Management Settings.

If you try to retrieve an ExperienceBundle from an org that doesn't have this setting enabled, no ExperienceBundle will be retrieved - this might mean that your community fails to deploy or that part of it is missing!

For example, I created a new community called CAP in an org that didn't have Enable ExperienceBundle Metadata API checked, retrieved it using workbench with a package.xml that included ExperienceBundle but didn't include SiteDotCom, and then tried to deploy that package to another org. The deployment partially succeeded but the new community didn't appear in my All Communities list, and I saw these errors in the Deployment Status for the deployment: In field: Name - no Network named CAP found, Network not found for the CustomBrand : cbCAP, and In field: PicassoSite - no SiteDotCom named CAP1 found.

When I tried to deploy an ExperienceBundle to an org that didn't have the Enable ExperienceBundle Metadata API setting enabled, my deployment failed reporting an error Not available for deploy for this organization for each item in the ExperienceBundle:

ExperienceBundle overrules SiteDotCom

Don’t use both the SiteDotCom and ExperienceBundle metadata types to deploy the same information about your communities because this can have unexpected results. If you include both the SiteDotCom and ExperienceBundle metadata types when you retrieve, Salesforce will give you the metadata in both formats. If you include both types when you deploy, the ExperienceBundle overrules the SiteDotCom; you have to be careful that any changes you want to deploy are included in the ExperienceBundle. In future, you might be able to include both metadata types without a problem because the ExperienceBundle is still in Developer Preview and might be changed before it becomes generally available.

Developer preview

At the moment, you can't deploy an ExperienceBundle to a production org; hopefully this will change in the future. Even without support for deploying to production, ExperienceBundle can still be super useful: use it while you're developing and testing and then use SiteDotCom just for that final deployment to production.

This feature is available as a Developer Preview, so the details might change.

[Update, May 21, 2020: The ExperienceBundle metadata type is now out of Developer Preview and can be deployed to production orgs.]

Want to try it out?

We're currently adding support for this new metadata type in Gearset. Let us know if you've used the ExperienceBundle metadata type and, more generally, if we can help you with deploying communities. Just get in touch with us via the in-app chat or by email. Alternatively, leave us a suggestion on our feedback forum.

Update: Not all communities are supported!

We've been playing around with communities some more, and discovered that not all of them are supported by the ExperienceBundle metadata type. When I tried to deploy a community called awesome that I created from the Aloha standard template, no ExperienceBundle was included in the package I retrieved from Salesforce. The message in the response was pretty to the point: ExperienceBundle Metadata API doesn't support the template of awesome1. Hopefully support for more templates will be added as time goes on! For the time being we'll have to fall back on SiteDotCom for these communities.