CustomPageWebLink Metadata Type in SFDX

Architectural Overview#

The CustomPageWebLink metadata type represents a standalone custom link that is not bound to a standard or custom object, historically used inside HomePageComponent link lists. While object-specific custom buttons and links use the WebLink metadata type under objects/<ObjectName>/webLinks/, CustomPageWebLink lives at the top-level weblinks/ folder and shares the same XML schema structure as WebLink.

Architects encounter CustomPageWebLink primarily during Classic-to-Lightning migrations, org dependency cleanups, and security audits (especially scanning for retired javascript link types or hard-coded instance URLs).

SFDX Directory and File Suffix#

Key Metadata Fields#

CustomPageWebLink shares its field structure with WebLink:

Declarative XML and package.xml Examples#

Source Format XML (Corporate_Compliance_Portal.customPageWebLink-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<CustomPageWebLink xmlns="http://soap.sforce.com/2006/04/metadata">
    <availability>online</availability>
    <description>Opens the enterprise compliance portal with the current user context.</description>
    <displayType>link</displayType>
    <encodingKey>UTF-8</encodingKey>
    <hasMenubar>false</hasMenubar>
    <hasScrollbars>true</hasScrollbars>
    <hasToolbar>false</hasToolbar>
    <height>600</height>
    <isResizable>true</isResizable>
    <linkType>url</linkType>
    <masterLabel>Corporate Compliance Portal</masterLabel>
    <openType>newWindow</openType>
    <position>none</position>
    <protected>false</protected>
    <showsLocation>false</showsLocation>
    <showsStatus>false</showsStatus>
    <url>https://compliance.example.com/sso?user={!$User.Username}</url>
</CustomPageWebLink>

Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Corporate_Compliance_Portal</members>
        <name>CustomPageWebLink</name>
    </types>
    <version>68.0</version>
</Package>

Querying via SOQL and Tooling API#

Under the hood, CustomPageWebLink records are stored in the WebLink table with PageOrSobjectType = 'CustomPageItem':

SELECT Id, Name, MasterLabel, LinkType, OpenType, Url, EncodingKey
FROM WebLink
WHERE PageOrSobjectType = 'CustomPageItem'
ORDER BY Name ASC

Retrieve or deploy using the sf CLI:

sf project retrieve start --metadata CustomPageWebLink:Corporate_Compliance_Portal

Architect Best Practices and Gotchas#

• Lightning Experience Modernization: Classic Home Page Custom Links (CustomPageWebLink) do not render on Lightning Home Pages (FlexiPage). For Lightning Experience, use the CustomHelpMenuSection for global links or a Rich Text / custom LWC component on the Lightning Home Page.
• Avoid Hard-Coded Org URLs: Never hard-code https://na1.salesforce.com or sandbox domains inside <url>. Use relative paths or {!$Api.Partner_Server_URL_680} / Custom Labels where external base URLs vary by environment.

Frequently asked questions

What is the difference between CustomPageWebLink and WebLink in Salesforce Metadata API?

WebLink belongs to a specific CustomObject (such as Account.Billing_Portal), whereas CustomPageWebLink is a standalone custom link used in Home Page Custom Link components.

Where are CustomPageWebLink files stored in SFDX source format?

They are stored in force-app/main/default/weblinks/ with the file suffix .customPageWebLink-meta.xml.

Are JavaScript OnClick CustomPageWebLink definitions supported in Lightning Experience?

No. CustomPageWebLink components with linkType javascript are blocked in Lightning Experience for security reasons and should be replaced with Lightning Web Components or Quick Actions.

How do I query CustomPageWebLink records in an org?

Query the WebLink sObject via SOQL or Tooling API where PageOrSobjectType equals CustomPageItem.