Integrate Your React App with the Agentforce 360 Platform (Beta)

A Salesforce Multi-Framework app is a web app that uses a non-Salesforce UI framework, such as React, and runs on the Agentforce 360 Platform. The UIBundle metadata type represents these apps in your Salesforce DX project.

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.

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 app’s metadata.

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

  • AppLauncher makes the app available 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.

For example, the UI bundle metadata that’s deployed with an external user app looks like this.

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

PropertyTypeDescription
outputDirstringRequired. The relative path to the directory that contains built application assets. The default value is "dist" for bundled apps.
apiVersionstringThe 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.
routingstringBlock containing custom URL handling. If omitted, standard file-based serving is used.
routing.fileBasedRoutingbooleanWhen true, URLs are automatically mapped to the folder structure in outputDir. Defaults to true.
routing.trailingSlashstringControls how the platform handles trailing slashes in URLs. Valid values are:
• never: Removes the slash (e.g., redirects "/page/" to "/page").
• always: Adds a slash (e.g., redirects "/page" to "/page/").
• auto: No change.
routing.fallbackstringSpecifies 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.rewritesarrayAn array of rewrite rules that serve a different file without changing the browser URL.
routing.rewrites.routestringRequired for rewrites. The source URL pattern. Supports named parameters (:id) and wildcards (*).
routing.rewrites.targetstringRequired for rewrites. The internal file path to serve.
routing.redirectsarrayAn array of redirect rules that return an HTTP redirect response to the client. Rules are evaluated in order.
routing.redirects.routestringRequired for redirects. The source URL pattern. Supports named parameters (:id) and wildcards (*).
routing.redirects.targetstringRequired for redirects. The destination URL.
routing.redirects.statusCodestringRequired 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 one of these templates, which provide the necessary UIBundle project structure and some basic features that differ by use case.

  • reactinternalapp: Use this template to create 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.
  • reactexternalapp: Use this template to create 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.

For a project that’s based on the reactexternalapp template, several additional metadata types are required to support the Experience Cloud site. The files are contained in these folders in force-app/main/default.

  • digitalExperienceConfigs: Represents configuration details for your org’s workspaces, such as the site label, site URL path prefix, and workspace type.
  • digitalExperiences: Represents a collection of related content items that form the site when combined with data from the DigitalExperienceConfig metadata type.
  • networks: Represents an Experience Cloud site.
  • sites: 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 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, to use the reactinternalapp or reactinternalapp project templates to scaffold your app according to your use case, use:

Alternatively, to generate a new Salesforce DX project based on the React 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.