Custom Application for React UI Bundles

Create and configure a Salesforce Custom Application that hosts a React UI bundle in Lightning Experience. This skill generates the CustomApplication metadata so the app appears in the Lightning App Launcher and can be accessed by internal users.

Custom Applications differ from Experience Sites: they don't need Networks, CustomSite, DigitalExperienceConfig, or DigitalExperienceBundle metadata. The Custom Application acts as a thin launcher entry that delegates rendering to the React UI bundle referenced by

uiBundle

Required Properties

Resolve all properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found.

Property	Format	How to Resolve
appName	`lowercamelcase` (e.g., `myInternalApp` )	The UI bundle name from `uiBundles/<name>/` directory
appNamespace	String	`namespace` in `sfdx-project.json` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → default `c`
appLabel	Human-readable string	User-provided, or derive from appName by converting camelCase to Title Case

The

appNamespace

and

appName

connect the Custom Application to the correct React UI bundle. In newer API versions this uses

<uiBundle>{appNamespace}__{appName}</uiBundle>

; in older versions it uses

<webApplication>{appName}</webApplication>

. Getting this wrong means the app launcher entry exists but shows a blank page. Step 2 of the workflow determines which field to use.

Generation Workflow

Step 1: Resolve All Required Properties

Determine values for all properties before constructing anything. Use the resolution strategies in the table above.

Step 2: Query API Context (Version-Aware Field Discovery)

Call

salesforce-api-context

MCP tools to discover which fields exist for the target org's API version. This ensures the generated metadata is compatible with the user's Salesforce version.

Required calls:

Call

get_metadata_type_fields

for

CustomApplication

— check whether the

uiBundle

field exists

Call
```
get_metadata_type_fields
```
for
```
UIBundle
```
— check whether the
```
target
```
field exists

Field resolution based on API response:

Field Check	If present	If absent (older API version)
`CustomApplication.uiBundle`	Use `<uiBundle>{appNamespace}__{appName}</uiBundle>`	Use `<webApplication>{appName}</webApplication>` (no namespace)
`UIBundle.target`	Use `<target>CustomApplication</target>`	Omit the `<target>` element entirely

salesforce-api-context

is unavailable after a real attempt, fall back to the newer field names (

uiBundle

target

Step 3: Create the Project Structure

Create any files and directories that don't already exist:

Metadata Type	Path
CustomApplication	`<sourceDir>/applications/{appName}.app-meta.xml`

Note:

<sourceDir>

is determined from

sfdx-project.json

. Read

packageDirectories[]

and use the entry where

"default": true

; the full source directory is

<path>/main/default

. If no default is set, use the first entry. Commonly

force-app/main/default

, but this path is configurable.

Step 4: Populate All Metadata Fields

Use the default template in the doc below. Values in

{braces}

are resolved property references — substitute them with the actual values from Step 1. Apply the field resolution from Step 2 to determine which XML elements to use.

Metadata Type	Template Reference
CustomApplication	configure-metadata-custom-application.md

Execution Note for Step 4: Load and use the doc

Agents MUST read the full contents of the docs/*.md file referenced in Step 4 before attempting to populate metadata fields.
Read the file in full, replace placeholders (e.g.
```
{appName}
```
) with the resolved values, then use the expanded template to populate the metadata XML content.
If Step 2 determined the older field names apply, substitute
```
<uiBundle>
```
with
```
<webApplication>
```
in the generated output.

Step 5: Update UI Bundle Meta XML

If Step 2 confirmed the

target

field exists on

UIBundle

, add

<target>CustomApplication</target>

to the

.uibundle-meta.xml

file (skip if the field doesn't exist in the org's API version):

xml

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>{appName}</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>

Step 6: Do Not Modify Non-Templated Properties

Do not modify any default property values for

CustomApplication

metadata that are not expressed as variables wrapped in

{braces}

Verification Checklist

Before deploying, confirm:

All required properties are resolved
API context was queried to determine available fields (Step 2)
```
applications/{appName}.app-meta.xml
```
exists with correct content
The bundle reference field matches the org's API version (
```
<uiBundle>
```
or
```
<webApplication>
```
)

target

field is supported:

.uibundle-meta.xml

has

<target>CustomApplication</target>

Deployment validates successfully:

bash

sf project deploy validate --metadata CustomApplication UIBundle --target-org ${usernameOrAlias}

generating-ui-bundle-custom-app

NPX Install

Tags

SKILL.md Content