--- schema_version: "1" id: 8c31cce957ef076116579bbbea9047f106715622bb15dac0af542f1bfa2825a5 title: Integrate Your React App with the Agentforce 360 Platform collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/salesforcedx/einsteinfordevs/guides/files/reactdev-integrate.md canonical_url: https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-integrate.html source_site: developer.salesforce.com content_type: documentation content_hash: 30edfa1511f8ac22efa90108b69113038b10b060c36f637814d7eb56df9da3c3 products: - Agentforce Vibes Developer Guide (Deprecated) - salesforcedx --- # 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. ```shell 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](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_source_file_format.htm). ### 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. ```shell externaluserapp A Salesforce UI Bundle. true 1 Experience ``` ### 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. | 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 (e.g., redirects "/page/" to "/page").
• `always`: Adds a slash (e.g., 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. ```shell { "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`). ```shell { "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](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/reactdev-acc.md). 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: ```shell 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: ```shell 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: ```shell 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`. ```shell 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](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_ui-bundle_commands_unified.htm) - _Salesforce CLI Command Reference_: [template generate ui-bundle](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_template_commands_unified.htm#cli_reference_template_generate_ui-bundle_unified) - _Salesforce CLI Command Reference_: [template generate project](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_template_commands_unified.htm#cli_reference_template_generate_project_unified) - _Salesforce CLI Command Reference_: [ui-bundle Commands](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_ui-bundle_commands_unified.htm) - _Metadata API Developer Guide_: [UIBundle](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_uibundle.htm)