Platform Flexipage Generate

When to Use This Skill

Use this skill when you need to:

• Create Lightning pages (RecordPage, AppPage, HomePage)
• Generate FlexiPage metadata XML
• Add components to existing FlexiPages
• Troubleshoot FlexiPage deployment errors
• Understand FlexiPage structure and component configuration
• Work with page layouts or Lightning page customization
• Edit or update ANY *.flexipage-meta.xml file

Specification

Overview

CRITICAL: When creating NEW FlexiPages, you MUST ALWAYS start with the CLI template command. Never create FlexiPage XML from scratch - the CLI provides valid structure, proper regions, and correct component configuration that prevents deployment errors.

Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping for component discovery and configuration.

Quick Start Workflow

Step 1: Bootstrap with CLI

MANDATORY FOR NEW PAGES: This step is NOT optional. Always use the CLI template command when creating a new FlexiPage. The CLI generates valid XML structure, proper regions, and correct metadata that prevents common deployment errors. Only skip this step if you're editing an existing FlexiPage file.

`<packageDirectory>` = the path value from sfdx-project.json → packageDirectories[0] (e.g., force-app). Read it from the project file before running commands.

sf template generate flexipage \
  --name <PageName> \
  --template <RecordPage|AppPage|HomePage> \
  --sobject <SObject> \
  --primary-field <Field1> \
  --secondary-fields <Field2,Field3> \
  --detail-fields <Field4,Field5,Field6,Field7> \
  --output-dir <packageDirectory>/main/default/flexipages

CRITICAL: If the sf template generate flexipage command fails, STOP.

1. Install the templates plugin: ``bash sf plugins install templates ``
2. Retry the sf template generate flexipage command
3. Verify the FlexiPage XML file was created

Do NOT continue to Step 2 until the template command succeeds. The generated XML is required for the entire workflow.

Template-specific requirements

RecordPage:

• Requires --sobject (e.g., Account, Custom_Object__c)
• Requires field parameters:
• --primary-field: Most important identifying field (e.g., Name)
• --secondary-fields: Record summary (recommended 4-6, max 12)
• --detail-fields: Full record details, including required fields (e.g., Name)

AppPage:

• No additional requirements

HomePage:

• No additional requirements

Field Selection Rules

• Validate fields exist: Use MCP tools or describe commands to discover available fields for the object before specifying them in the command
• Prefer compound fields: Use Name (not FirstName/LastName), BillingAddress (not BillingStreet/BillingCity/BillingState), MailingAddress, etc. when available
• Include required fields in detail-fields: Always include object required fields (like Name) in the --detail-fields parameter, even if they're also used in --primary-field or --secondary-fields

What you get

• Valid FlexiPage XML with correct structure
• Pre-configured regions and basic components
• Proper field references and facet structure
• Ready to deploy as-is or enhance further

Step 2: Deploy Base Page

Run a dry-run deployment to validate the page and dependencies (use the default package directory from sfdx-project.json):

sf project deploy start --dry-run -d "<packageDirectory>/main/default" --test-level NoTestRun --wait 10 --json

Critical: Fix any deployment errors before proceeding. The page must validate successfully.

Step 3: Add Components Dynamically (if requested)

After the base page deploys successfully, if the user wants additional components, follow the Adding Components Dynamically workflow below. All component additions MUST go through the discovery and inference pipeline — never write component XML from memory alone.

Critical XML Rules

Read `references/xml_rules.md` for all XML encoding rules, field reference format, region/facet types, fieldInstance structure, unique identifier requirements, and common deployment error resolutions.

Key rules (quick reminder):

• Encode HTML in <value> tags: & first, then <, >, ", '
• Field references: Record.{FieldApiName} (never Object.Field)
• Every <identifier> and region <name> must be unique across the file
• Multiple components in same facet → combine in ONE region with multiple <itemInstances>

Identifiers, Regions, and Containers

Read `references/identifiers_and_regions.md` for the identifier generation algorithm, facet naming patterns (named vs UUID), region selection rules, and container component facet structure.

Component-Specific Tips

dynamicHighlights (RecordPage Header)

Location: header region only. See references/record_flexipage_dynamicHighlights.md for full structure. CLI generates Facets automatically from --primary-field and --secondary-fields.

fieldSection

Use for: Displaying fields in columns. Three-level nesting: Region → Column Facets → Field Facets. See references/flexipage_fieldSection.md for full structure and XML example. Critical: The columns property value is a Facet name, not a number.

richText

See references/flexipage_richText.md for encoding rules and XML structure. Identifier: flexipage_richText or flexipage_richText_{N}

Required Metadata Structure

<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
   <flexiPageRegions>
      <!-- Regions and components here -->
   </flexiPageRegions>
   <masterLabel>Page Label</masterLabel>
   <template>
      <name>flexipage:recordHomeTemplateDesktop</name>
   </template>
   <type>RecordPage</type>
   <sobjectType>Object__c</sobjectType> <!-- RecordPage only -->
</FlexiPage>

Page Types:

• RecordPage - requires <sobjectType>
• AppPage - no sobjectType
• HomePage - no sobjectType

Validation Checklist

Structure (new pages)

• [ ] Used CLI to bootstrap — never create FlexiPage XML from scratch

Identifiers & Regions

• [ ] All <identifier> values unique across entire file
• [ ] All region/facet <name> values unique across entire file
• [ ] Multiple components in same facet combined in ONE region with multiple <itemInstances>

Field Instances

• [ ] All field references use Record.{Field} format
• [ ] Each fieldInstance has fieldInstanceProperties with uiBehavior
• [ ] Each fieldInstance in its own <itemInstances> wrapper

Types & Encoding

• [ ] Template regions use <type>Region</type>; component facets use <type>Facet</type>
• [ ] Property values with HTML/XML are entity-encoded
• [ ] No unnecessary <mode> tags (only where component patterns require them)
• [ ] No __c suffix in page names
• [ ] Each Facet referenced by exactly one component property

Quick Reference: CLI Command

Read `references/cli_commands.md` for full CLI examples (RecordPage, AppPage, HomePage) and available options.

Adding Components Dynamically

MANDATORY WORKFLOW: ALL component additions to a FlexiPage MUST follow this workflow. Do not write component XML from memory or skip discovery. This applies to standard OOTB components, custom LWC components, and any other component type.

Overview

When the user requests components (e.g., "add a related list of contacts and a report"), follow this pipeline:

1. Parse Intent → identify ALL requested components
2. Discover ALL → batch components through 3-tier discovery
3. Infer Properties → run 3-step inference for EACH discovered component
4. Generate XML → produce valid XML for all components together
5. Validate → check identifiers, regions, property completeness