Why HomePageLayout Still Appears in Modern CI/CD Pipelines

In Lightning Experience, home pages are built in Lightning App Builder and stored as FlexiPage metadata (<type>HomePage</type>). However, HomePageLayout (homePageLayouts/<Name>.homePageLayout-meta.xml) represents the Salesforce Classic Home Page Layout, and it frequently surfaces in modern DevOps pipelines for one critical reason:

  • Profile Dependencies (homePageLayoutAssignments): Every Profile metadata file can contain a <homePageLayoutAssignments> element referencing a HomePageLayout (such as DE Default). If you deploy a Profile to a Scratch Org or Sandbox where that HomePageLayout is missing, the deployment fails unless you either deploy the HomePageLayout or strip the assignment.
Salesforce Classic Home Lightning Experience Home HomePageLayout(homePageLayouts/DE Default.homePageLayout-meta.xml) Profile(layoutAssignments / homePageLayoutAssignments) FlexiPage (type: HomePage)(flexipages/Sales_Home.flexipage-meta.xml) CustomApplication(profileActionOverrides)

Key Metadata Fields on HomePageLayout

Field Type Required Description
narrowComponents string[] No Components displayed in the left narrow sidebar column (e.g., standard-CreateNew, standard-RecentItems, standard-MessagesAndAlerts).
wideComponents string[] No Components displayed in the main wide body column (e.g., standard-Dashboard, standard-Calendar, standard-Tasks).

Real-World XML Example (homePageLayouts/DE Default.homePageLayout-meta.xml)

XML
<?xml version="1.0" encoding="UTF-8"?>
<HomePageLayout xmlns="http://soap.sforce.com/2006/04/metadata">
    <narrowComponents>standard-StandardSearch</narrowComponents>
    <narrowComponents>standard-CreateNew</narrowComponents>
    <narrowComponents>standard-RecentItems</narrowComponents>
    <wideComponents>standard-Dashboard</wideComponents>
    <wideComponents>standard-Tasks</wideComponents>
    <wideComponents>standard-Calendar</wideComponents>
</HomePageLayout>

Classic HomePageLayout vs. Lightning FlexiPage (HomePage)

Feature HomePageLayout (Classic) FlexiPage (type: HomePage)
Metadata Folder homePageLayouts/ flexipages/
Target UI Salesforce Classic only Lightning Experience & Mobile
Component Types HomePageComponent & standard-* widgets LWC (LightningComponentBundle), Aura, Dashboards, Flows
Assignment Mechanism Profile (homePageLayoutAssignments) Org Default, CustomApplication (actionOverrides), or App + Profile (profileActionOverrides)

Tip

How to Assign Lightning Home Pages in Metadata: If you want to deploy a Lightning Experience Home Page assignment via SFDX, do not use HomePageLayout. Instead, deploy a FlexiPage with <type>HomePage</type> and reference it inside your CustomApplication (<profileActionOverrides><actionName>Tab</actionName><content>Sales_Home</content><pageOrSobjectType>standard-home</pageOrSobjectType>...</profileActionOverrides>).

Frequently asked questions

What is the difference between HomePageLayout and a Lightning Home Page?

HomePageLayout configures the Salesforce Classic home tab (using narrowComponents and wideComponents), whereas Lightning Experience home pages are stored as FlexiPage metadata files with type set to HomePage.

Why do HomePageLayout references still cause Profile deployment failures in Lightning orgs?

User Profiles store a homePageLayoutAssignments block that maps the profile to a HomePageLayout. If a Profile in your repository references a HomePageLayout that does not exist in the target org, deploying the Profile fails even if your users only use Lightning Experience.

What are the valid values for narrowComponents and wideComponents on HomePageLayout?

Valid standard component names include standard-Calendar, standard-Tasks, standard-Dashboard, standard-RecentItems, standard-CreateNew, standard-MessagesAndAlerts, standard-StandardSearch, and custom HomePageComponent names.

Comments

Questions, corrections and tips are welcome. Comments are GitHub Discussions, so you sign in with GitHub.