Integrate Your React App with the Agentforce 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 Agentforce 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.

React App Project Structure

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.

my-sfdx-project
└── force-app/
    └── main/
        └── default/
              └── uiBundles/
                    └── myapp/
                        ├── myapp.uibundle-meta.xml    		# Salesforce metadata
                        ├── ui-bundle.json               		# Application configuration
                        ├── package.json              		# Application dependencies
                        ├── vite.config.ts            		# Vite configuration
                        ├── vitest.config.ts           		# Vitest configuration
                        ├── tsconfig.json              		# TypeScript configuration
                        ├── src/
                        │   ├── app.html             		    # Entry HTML
                        │   ├── components/           		# React components
                        │   ├── pages/                		# Application pages
                        │   ├── assets/               		# Images, fonts, icons
                        │   └── styles/              		    # Global styles
                        └── dist/                    		    # Build output (generated)
├── sfdx-project.json                      				# SFDX project configuration
└── package.json                           				# Root workspace configuration

note: 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

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, when used with the CustomApplication metadata type, indicates that the app is an internal-facing app and makes it 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.

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

The ui-bundle.json File

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.

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

{
  "outputDir": "dist",
  "apiVersion": "v66.0",
  "routing": {
    "fileBasedRouting": true,
    "trailingSlash": "never",
    "fallback": "index.html",
    "rewrites": [
      {
        "route": "/products/:id",
        "target": "/product-detail.html"
      },
      {
        "route": "/legacy/*",
        "target": "/app.html"
      }
    ],
    "redirects": [
      {
        "route": "/old-home",
        "target": "/",
        "statusCode": 301
      },
      {
        "route": "/promo",
        "target": "/sale",
        "statusCode": 302
      },
    ]
  }
}

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).

{
  "outputDir": "dist",
  "routing": {
    "trailingSlash": "never",
    "fallback": "index.html"
  }
}

Internal and External App Files

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.

reactinternalapp

Use this 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.

For a project that's based on the reactinternalapp template, the CustomApplication metadata type is also required. This type is used to define and configure a Salesforce app, and controls the structure and behavior of your app. 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 React app (represented by UIBundle), such as c__propertymanagementapp, which ensures that the app appears in the App Launcher.

note: 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.

reactexternalapp

Use this 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.

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: The DigitalExperienceConfigs 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 DigitalExperiences 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).

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

Generate a React App and Install Dependencies

Generate Your App

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:

sf template generate ui-bundle --name MyReactApp --template reactbasic

Or, to use the reactinternalapp or reactinternalapp project templates to scaffold your app according to your use case, use:

sf template generate ui-bundle --name MyReactApp --template reactinternalapp

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

sf template generate project --name MyReactProject --template reactexternalapp

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

Install Dependencies

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.

cd force-app/main/default/uiBundles/MyReactProject
npm install
npm run sf-project-setup

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.

See Also

• Salesforce CLI Command Reference: ui-bundle Commands
• Salesforce CLI Command Reference: template generate ui-bundle
• Salesforce CLI Command Reference: template generate project
• Salesforce CLI Command Reference: ui-bundle Commands
• Metadata API Developer Guide: UIBundle