Integrate Your React App with the Headless 360 Platform

A Salesforce Multi-Framework app is a web app that uses a non-Salesforce UI framework, such as React, and runs on the Headless 360 platform. The UIBundle metadata type represents the UI for these apps in your Salesforce DX project and works with several other metadata types to define your app in Salesforce.

When deployed, this metadata creates a UIBundle record in Salesforce that establishes the app’s identity on the platform and declares which containers can host it. Salesforce CMS provides storage for application artifacts, such as runtime assets, images, and metadata, with versioning and publication lifecycle management.

If you prefer to develop your app using Agentforce Vibes, check out Build a React App Using Agentforce Vibes in the Agentforce Vibes Developer Guide.

Let’s take a closer look at the files and metadata required to run a React app on the Headless 360 platform.

The Salesforce DX project structure includes a force-app/main/default folder that contains a uiBundles folder. Application metadata and content live together in this top-level uiBundles directory. Each application subdirectory is a complete, self-contained unit with its own metadata definition (.uibundle-meta.xml), runtime configuration (ui-bundle.json), source code, and compiled assets.

The UIBundle metadata type can contain up to 2,500 files.

For more information, see Salesforce DX Project Structure and Source Format.

The .uibundle-meta.xml file, which is located in the force-app/main/default/uiBundles/{app_name} folder, defines the metadata for the app’s UI.

React apps are supported for use with two Salesforce targets, which you specify in the target property in this file.

CustomApplication indicates that the app is an internal, employee-facing app for use in the App Launcher. This is the default target if you don’t specify a value.
Experience indicates that the app is an external-facing site or portal and makes it available in the Digital Experiences app.

:::important In both cases, additional metadata types are required to integrate your app with the Headless 360 platform and make it available in the UI. For example, to make an internal app available in the App Launcher, you also need a CustomApplication metadata type that references the app. See the Internal and External Files section. :::

Here’s an example of the UI bundle metadata that’s deployed with an internal user app.

The ui-bundle.json file, located in the force-app/main/default/uiBundles/{app_name} folder, is the app’s runtime configuration file. The file can include these properties.

Property	Type	Description
`outputDir`	string	Required. The relative path to the directory that contains built application assets. The default value is “`dist`” for bundled apps.
`apiVersion`	string	The Salesforce API version. Uses the format “`vXX.X`”; for example, “`v66.0`”. Be sure to use the same API version as the Salesforce org where you’re deploying your app. Defaults to the current org version.
`routing`	string	Block containing custom URL handling. If omitted, standard file-based serving is used.
`routing.fileBasedRouting`	boolean	When `true`, URLs are automatically mapped to the folder structure in `outputDir`. Defaults to `true`.
`routing.trailingSlash`	string	Controls how the platform handles trailing slashes in URLs. Valid values are: • `never`: Removes the slash (for example, redirects “/page/” to “/page”). • `always`: Adds a slash (for example, redirects “/page” to “/page/”). • `auto`: No change.
`routing.fallback`	string	Specifies the file to serve when a request doesn’t match any static asset or explicit rule. Set to `index.html` to allow client-side routing for single-page apps (SPAs).
`routing.rewrites`	array	An array of rewrite rules that serve a different file without changing the browser URL.
`routing.rewrites.route`	string	Required for `rewrites`. The source URL pattern. Supports named parameters (`:id`) and wildcards (`*`).
`routing.rewrites.target`	string	Required for `rewrites`. The internal file path to serve.
`routing.redirects`	array	An array of redirect rules that return an HTTP redirect response to the client. Rules are evaluated in order.
`routing.redirects.route`	string	Required for `redirects`. The source URL pattern. Supports named parameters (`:id`) and wildcards (`*`).
`routing.redirects.target`	string	Required for `redirects`. The destination URL.
`routing.redirects.statusCode`	string	Required for `redirects`. The HTTP status for the redirect: • 301: Moved permanently (cacheable) • 302: Found (temporary, not cached) • 307: Temporary redirect (preserves request method, not cached) • 308: Permanent redirect (preserves request method, cacheable)

This example shows all possible configuration options for a ui-bundle.json file.

This example shows a typical configuration file for a React app, which ensures that the app works correctly when a user refreshes the page on a sub-route (for example, /dashboard).

When you create a React app, you can choose to use a reactinternalapp or a reactexternalapp template, which provides the necessary UIBundle project structure and some basic features and related metadata that differ by use case.

Use the reactinternalapp template to create internal-facing apps for employees signing in with their Salesforce credentials. The template includes an Agentforce Conversation Client and object search. To use this template, make sure that you follow the configuration steps in Configure Agentforce Conversation Client.

Projects that are based on the reactinternalapp template also require the CustomApplication metadata. This type defines and configures a Salesforce app, and connects your app to the App Launcher. The force-app/main/default/applications folder contains the .app-meta.xml file, which includes a field called uiBundle. This field contains the fully qualified name of the UIBundle that represents your React app, such as c__propertymanagementapp.

By referencing your app in .app-meta.xml and setting the UIBundle’s target field to CustomApplication in the .uibundle-meta.xml file, your app appears in the App Launcher.

Similar to a standard Salesforce app, you can control user access to the app using profiles and permission sets. Retrieving a component of this metadata type in a project makes the component appear in any Profile and PermissionSet components that are retrieved in the same package.

Use the reactexternalapp template to create external-facing apps for business to business (B2B) and business to consumer (B2C) use cases, such as partners or customers signing in from outside your org. The template provides a prebuilt shell that includes an Experience Cloud site with several pages, navigation, authentication, and object search.

Projects that are based on the reactexternalapp template also require several additional metadata types to support the Experience Cloud site. The files are contained in these folders in force-app/main/default:

digitalExperienceConfigs: The DigitalExperienceConfig metadata type represents the configuration details for your org’s workspaces, such as the site label, site URL path prefix, and workspace type.
digitalExperiences: The DigitalExperience metadata type represents a collection of related content items that form the site when combined with data from the DigitalExperienceConfig metadata type.
networks: The Network metadata type represents an Experience Cloud site.
sites: The CustomSite metadata type represents a Salesforce site.

Unlike a standard LWR site, the digitalExperiences folder contains only the sfdc_cms_site folder. In the content.json file in the folder:

The appContainer property is set to true to indicate that the site is used in a React app.
The appSpace property refers to the related React app. Make sure that the value uses the format NamespacePrefix__DeveloperName (for example, MyNamespace__MyWebApp or c__MyWebApp for orgs without a registered namespace).

You can’t edit a React app’s Experience Cloud site in Experience Builder.

Use familiar Salesforce DX workflows and CLI commands to build and manage React apps alongside other Salesforce metadata.

Use the sf template generate ui-bundle CLI commands to generate a React-based UI bundle that contains the code and metadata to build a React app.

For example, to generate a React-based web application in an existing DX project, use:

Or use the reactinternalapp or reactexternalapp project templates to scaffold your app according to your use case. For example, to generate a new Salesforce DX project based on the internal React app template, use:

The generated project includes the required UIBundle metadata, along with the required CustomApplication metadata type.

Alternatively, to generate a new project based on the external app template, use:

The generated project includes the required UIBundle metadata, along with the required site metadata types.

To install the project dependencies for your UI bundle, use npm install. Make sure that you install the dependencies inside the uiBundle directory.

For example, this command installs the dependencies in the correct folder, builds the app, and then opens the dev server at http://localhost:5173.

If you’re building a React app without using a React-specific template, consider installing these plugins to help you along.

@salesforce/vite-plugin-ui-bundle: This plugin is helpful for local development. It helps wire up the Vite dev server to run the application locally with access to data in your org.
@salesforce/ui-bundle: This plugin contains helper functions to expedite working with the data SDK.

Multi-Framework recipes repo
Salesforce CLI Command Reference: ui-bundle Commands
Salesforce CLI Command Reference: template generate ui-bundle
Salesforce CLI Command Reference: template generate project
Metadata API Developer Guide: UIBundle