You've built the perfect Lightning record page. Custom components, streamlined layouts, everything your sales team requested. Now you need to deploy it to production, along with its page assignments that control who sees what.

Here's where things get tricky. Lightning record page assignments don't deploy like other Salesforce metadata. Miss a step, and your users either see the wrong page or nothing new at all. Deploy incorrectly, and you can overwrite existing assignments, changing the experience for other teams.

The short answer: to deploy a Lightning record page and its assignment, you deploy the page itself (the FlexiPage metadata) together with the metadata that holds the assignment. App-level and profile-level assignments live in the CustomApplication metadata, and the org default assignment lives in the object (CustomObject) metadata. Deploy the FlexiPage on its own and the page arrives in the target org, but no one is pointed at it. The rest of this guide shows exactly which components to include for each assignment type, and how to deploy them with change sets, the Salesforce CLI, or Flosum.

Whether you're using change sets, Salesforce CLI, or a DevOps tool like Flosum, these patterns will save you from the Monday morning flood of “where did my page go?” tickets.

What Metadata Is Required to Deploy a Lightning Record Page?

A Lightning record page is stored as FlexiPage metadata. The page and its assignment are two separate things: deploying the FlexiPage moves the layout and its components, but the assignment (which users, apps, and objects actually see the page) is stored elsewhere. That separation is the single most common reason a page “deploys fine” but nobody sees it.

Assignments come in a few scopes, from broadest to most specific:

• Org default: the page every user sees for an object unless a more specific assignment applies. Stored on the object (CustomObject) metadata.
• App default: the page users see for that object inside a specific Lightning app. Stored on the app (CustomApplication) metadata.
• App + profile: overrides the app default for specific profiles.
• App + profile + record type: the most specific scope, narrowing the assignment to a record type as well.

Salesforce applies the most specific matching assignment first, then falls back to the app default, then the org default, and finally the standard system page if nothing else matches. You don't need to model this precedence by hand; you just need to deploy the right metadata for the scope you're targeting. The matrix below shows which components to include for each one.

Lightning Record Page Assignment Metadata by Assignment Type

Three metadata types do the work. Keeping them straight is what makes the difference between a clean deployment and an overwritten app.

FlexiPage (the page itself)

The Lightning record page lives in a .flexipage-meta.xml file. This is the layout and its components. Deploying it creates or updates the page in the target org, but on its own it does not point any user at the page.

CustomObject (the org default assignment)

The org default assignment is stored as an actionOverride inside the object's metadata. A minimal example that sets an org default record page for the Account object looks like this:

<actionOverrides>
    <actionName>View</actionName>
    <content>Account_Sales_Page</content>
    <formFactor>Large</formFactor>
    <type>Flexipage</type>
</actionOverrides>

To deploy the org default, include the FlexiPage and the object (CustomObject), plus any record types involved.

CustomApplication (app, profile, and record type assignments)

App-level assignments, including app default, app + profile, and app + profile + record type, are stored as profileActionOverrides inside the Lightning app's metadata. A profile-specific assignment looks like this:

<profileActionOverrides>
    <actionName>View</actionName>
    <content>Account_Sales_Page</content>
    <formFactor>Large</formFactor>
    <pageOrSobjectType>Account</pageOrSobjectType>
    <recordType>Account.Business</recordType>
    <type>Flexipage</type>
    <profile>Sales</profile>
</profileActionOverrides>

Omit the <profile> line and this becomes the app default; omit <recordType> and it applies to all record types. Because these overrides live inside the CustomApplication, deploying the app deploys every assignment it contains, which is why reviewing the diff before deployment matters (more on that below). The profile metadata and record types referenced here must already exist in, or deploy alongside, the target org.

Prerequisites Before Deployment

Before you deploy, confirm you have each of these, and that each already exists in the target org or is included in your deployment:

• The page API name (the FlexiPage developer name).
• The object the page is built for.
• The Lightning app(s) the page is assigned in, for app-level assignments.
• The record type(s) involved, if the assignment is record-type specific.
• The profile(s) involved, for profile-level assignments.
• The components on the page, including any custom Lightning components, so the page doesn't fail to load in the target org.
• The form factors you're assigning (desktop / Large and phone / Small), since assignments are set per form factor.

Confirming these up front prevents the most common failure mode: the page deploys, but a referenced profile, record type, or component is missing in the target org, so the assignment silently doesn't take effect.

How to Deploy a Lightning Record Page with Change Sets

Change sets are the most accessible option for admins who prefer a point-and-click deployment between connected orgs. Here is the process:

1. In the source org, go to Setup, then Outbound Change Sets, and click New.
2. Add the page: choose the “Lightning Page” component type and select your record page. This adds the FlexiPage.
3. Add the metadata that holds the assignment. For an app-level assignment, add the Custom Application. For the org default, add the object. Then add any Profiles and Record Types the assignment references.
4. Use “View/Add Dependencies” to pull in referenced components, but review the list carefully so you don't sweep in unrelated app metadata you didn't intend to change.
5. Upload the change set to the target org.
6. In the target org, go to Setup, then Inbound Change Sets, click Validate to check for errors, then Deploy.
7. Confirm the page and its assignment in Lightning App Builder (covered below).

One caution specific to change sets: adding a Custom Application deploys that app's full set of assignments, so if other teams manage assignments in the same app, review the change carefully to avoid overwriting theirs.

How to Deploy a Lightning Record Page with Salesforce CLI

The Salesforce CLI gives developers precise, scriptable control and fits naturally into a version-controlled workflow. Retrieve the FlexiPage along with whichever metadata holds the assignment:

sf project retrieve start --metadata FlexiPage:Account_Sales_Page CustomApplication:Sales_Console --target-org dev-sandbox

For an org default assignment, retrieve the object instead of (or in addition to) the app:

sf project retrieve start --metadata FlexiPage:Account_Sales_Page CustomObject:Account --target-org dev-sandbox

A manifest keeps larger deployments explicit and repeatable. A package.xml for an app + profile assignment looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Account_Sales_Page</members>
        <name>FlexiPage</name>
    </types>
    <types>
        <members>Sales_Console</members>
        <name>CustomApplication</name>
    </types>
    <types>
        <members>Sales</members>
        <name>Profile</name>
    </types>
    <version>62.0</version>
</Package>

Validate before you deploy, then deploy for real:

sf project deploy start --manifest package.xml --target-org production --dry-run
sf project deploy start --manifest package.xml --target-org production

The validate-only run (--dry-run) confirms the metadata is well-formed and its dependencies exist in the target org before anything changes. For the full metadata structure of the page, see Salesforce's Metadata API guide.

How to Deploy Lightning Record Page Assignments with Flosum

Flosum runs entirely inside Salesforce and treats Lightning pages and their assignments as first-class, deployable components, which removes most of the guesswork from the process. As a Salesforce-native DevOps tool, it handles the FlexiPage and its assignment metadata together and shows you exactly what will change before you commit.

A typical Flosum deployment of a Lightning record page assignment looks like this:

1. Connect your source and target orgs, then create a branch or change set for the deployment.
2. Select the components to deploy: the Lightning page (FlexiPage) and its assignment metadata (the Custom Application for app and profile assignments, or the object for the org default), plus referenced profiles and record types.
3. Compare the assignment metadata between the source and target orgs. This side-by-side comparison shows precisely which assignments will change, so you don't overwrite another team's assignments in a shared app.
4. Deploy. Flosum sequences the components and gives you a clear success or failure status.
5. If something isn't right, roll back to the previous state in a couple of clicks rather than manually rebuilding assignments.

The practical advantage over manual change sets is visibility and reversibility: you see the exact assignment diff before deploying, the whole action is logged for audit, and rollback is immediate if a deployment causes problems.

How to Validate a Lightning Record Page Deployment

Validation catches problems before they reach users. There are three layers worth running, in order.

First, a deployment preview or metadata comparison. Before deploying, compare the assignment metadata in your source against the target org so you can see exactly which assignments will be added, changed, or removed. This is the step that prevents accidental overwrites of unrelated assignments in a shared app.

Second, a validation-only deployment. Run a validate (change sets) or a --dry-run deploy (CLI) to confirm the metadata is well-formed and that every referenced profile, record type, and component already exists in the target org. This catches missing-dependency failures without touching production.

Third, user-context testing after the deploy completes. A deployment can succeed technically while still pointing the wrong users at the wrong page, so the only reliable confirmation is opening a record as the affected users. The checklist below covers the contexts to test.

Post-Deployment Testing Checklist

Work through each context the page is meant to serve. One matrix covers it:

How to Verify That the Assignment Is Active

Verification is straightforward once you know where to look. Do it in three quick checks rather than watching real-time logs.

• Deployment status: confirm the deployment itself reported success in change sets, the CLI output, or Flosum.
• Metadata comparison: compare the assignment metadata in the target org against what you intended to deploy, to confirm the assignment actually landed rather than just the page.
• UI verification: confirm the assignment in Lightning App Builder and as a test user, as described next.

Verify the Page in Lightning App Builder and as a Test User

In the target org, open the FlexiPage in Lightning App Builder (Setup, then Lightning App Builder, then Edit on the page), and open its Activation settings. You should see your intended assignment listed: the app, the profile, the record type, or the org default, for each form factor you assigned. If the expected assignment isn't there, the page deployed but its assignment did not.

Then confirm from the user's side. Log in as a test user (or use Login As) with the target profile, open the relevant Lightning app, and open a record of the object. You should see the new page. Repeat on both desktop and mobile, because assignments are set per form factor and a desktop assignment does not automatically cover phone.

Best Practices for Reliable Lightning Page Deployments

A few habits keep Lightning page deployments predictable as your org grows:

• Compare the target org before every deployment, including dependencies, so you never overwrite unrelated app metadata or another team's assignments by accident.
• Deploy the page and its assignment together, never separately. A FlexiPage without its assignment metadata leaves users on the old page.
• Keep a rollback path, whether that's a tagged version in source control or a Flosum snapshot, so you can restore the previous assignment quickly if something breaks.
• Audit assignments periodically and retire orphaned assignments that point to deprecated profiles or record types, since they add clutter and make troubleshooting harder.
• Document which page is assigned where, by object, app, profile, and record type, so the next person doesn't have to reverse-engineer it.
• Test in a sandbox that mirrors the target's profiles, apps, and record types, so a deployment that validates in the sandbox behaves the same way in production.

Deploy Lightning Record Pages with Flosum

Deploying a Lightning record page comes down to three things: deploy the page together with the right assignment metadata, validate and preview the change before it reaches production, and verify the assignment in the UI afterward. Change sets and the Salesforce CLI can all do this; the difference at scale is how much visibility and safety you have while you do it.

Flosum gives you a clear metadata comparison before you deploy, deploys the page and its assignments as one native action inside Salesforce, and lets you roll back in a couple of clicks if anything looks wrong, so a page assignment change never becomes a production incident. Request a demo with Flosum to see the Lightning record page deployment workflow end to end.

Frequently Asked Questions