CommunityThemeDefinition Metadata Type in SFDX

Architectural Overview#

Enterprise design systems require strict visual consistency across customer, partner, and employee Experience Cloud portals. The CommunityThemeDefinition metadata type packages a complete custom theme for Experience Builder, binding custom theme layout components (Aura or Lightning Web Components) to standardized layout slots (Home, Inner, Login) and associating them with a BrandingSet.

When architects distribute a corporate design system across multiple Salesforce orgs or business units, CommunityThemeDefinition ensures that administrators selecting the corporate theme in Experience Builder -> Theme automatically receive the approved header/footer shell components (customThemeLayoutType), color tokens (defaultBrandingSet), and preview thumbnails (bundlesInfo).

SFDX Directory and File Suffix#

Key Metadata Fields#

The CommunityThemeDefinition schema governs how Experience Builder maps page layout regions to custom shell components and branding tokens.

CommunityThemeSetting Subtype Fields#

Declarative XML Example#

The following Partner_Portal_Theme.communityThemeDefinition-meta.xml configures a corporate theme with standard Home, Inner, and Login layout shells plus a custom FullWidthLanding layout type for marketing campaigns.

<?xml version="1.0" encoding="UTF-8"?>
<CommunityThemeDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <bundlesInfo>
        <description>WCAG 2.1 AA compliant contrast tokens and responsive navigation shell.</description>
        <order>1</order>
        <title>Accessible Enterprise Design System</title>
        <type>Highlight</type>
    </bundlesInfo>
    <bundlesInfo>
        <description>Preview of the responsive partner portal theme header and hero region.</description>
        <image>Partner_Theme_Preview_Asset</image>
        <order>1</order>
        <title>Partner Portal Shell</title>
        <type>PreviewImage</type>
    </bundlesInfo>
    <customThemeLayoutType>
        <description>Edge-to-edge layout without sidebar padding for product launch pages.</description>
        <label>FullWidthLanding</label>
    </customThemeLayoutType>
    <defaultBrandingSet>Partner_Portal_Branding</defaultBrandingSet>
    <description>Standardized corporate theme for B2B partner and distributor portals.</description>
    <enableExtendedCleanUpOnDelete>true</enableExtendedCleanUpOnDelete>
    <masterLabel>Acme Partner Design System</masterLabel>
    <publisher>Acme Digital Experience Platform Team</publisher>
    <themeSetting>
        <customThemeLayoutType>FullWidthLanding</customThemeLayoutType>
        <themeLayout>c:partnerFullWidthThemeLayout</themeLayout>
    </themeSetting>
    <themeSetting>
        <themeLayout>c:partnerHomeThemeLayout</themeLayout>
        <themeLayoutType>Home</themeLayoutType>
    </themeSetting>
    <themeSetting>
        <themeLayout>c:partnerInnerThemeLayout</themeLayout>
        <themeLayoutType>Inner</themeLayoutType>
    </themeSetting>
    <themeSetting>
        <themeLayout>c:partnerLoginThemeLayout</themeLayout>
        <themeLayoutType>Login</themeLayoutType>
    </themeSetting>
</CommunityThemeDefinition>

package.xml Manifest#

Include the underlying LWC or Aura theme layout bundles, the BrandingSet, and any ContentAsset preview images alongside CommunityThemeDefinition:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Partner_Portal_Theme</members>
        <name>CommunityThemeDefinition</name>
    </types>
    <types>
        <members>Partner_Portal_Branding</members>
        <name>BrandingSet</name>
    </types>
    <types>
        <members>partnerHomeThemeLayout</members>
        <members>partnerInnerThemeLayout</members>
        <members>partnerLoginThemeLayout</members>
        <members>partnerFullWidthThemeLayout</members>
        <name>LightningComponentBundle</name>
    </types>
    <types>
        <members>Partner_Theme_Preview_Asset</members>
        <name>ContentAsset</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval and Deployment#

Use the Salesforce CLI to retrieve and deploy CommunityThemeDefinition components across scratch orgs and sandboxes:

# Retrieve a specific CommunityThemeDefinition and its BrandingSet
sf project retrieve start \
  --metadata CommunityThemeDefinition:Partner_Portal_Theme \
  --metadata BrandingSet:Partner_Portal_Branding

# Deploy the theme definition to a target org
sf project deploy start --source-dir force-app/main/default/communityThemeDefinitions/Partner_Portal_Theme.communityThemeDefinition-meta.xml

Architect Best Practices and Gotchas#

• Component Target Validation: Every component referenced in <themeLayout> must be deployed either before or in the same transaction as CommunityThemeDefinition, and it must explicitly declare lightningCommunity__Theme_Layout (for LWC) or forceCommunity:themeLayout (for Aura).
• Namespace Prefixing in Packages: When packaging CommunityThemeDefinition inside a namespaced Second-Generation Managed Package (2GP), reference local theme layout components with the package namespace prefix (or c: in unlocked/unmanaged source that resolves during packaging).
• BrandingSet Coupling: If defaultBrandingSet is specified, omitting the corresponding BrandingSet metadata file from your deployment manifest will fail the deployment with a missing reference error.

Frequently asked questions

What does CommunityThemeDefinition control in Experience Cloud?

CommunityThemeDefinition defines a custom theme in Experience Builder, mapping custom theme layout components to specific page layout types like Home, Inner, and Login alongside a default branding set.

Where are CommunityThemeDefinition files located in SFDX?

They are stored in force-app/main/default/communityThemeDefinitions/ with the .communityThemeDefinition-meta.xml file extension.

What component interfaces are required for a custom themeLayout?

An Aura component must implement forceCommunity:themeLayout, or a Lightning Web Component must declare the lightningCommunity__Theme_Layout target in its .js-meta.xml file.

How is CommunityThemeDefinition linked to a branding set?

The defaultBrandingSet element references the DeveloperName of a BrandingSet metadata component that defines the color palette, typography, and header imagery.