Project Structure and Metadata

A Multi-Framework app lives in your Salesforce DX project as a UIBundle. The UIBundle represents your app’s UI and works with several other metadata types to define the app on the platform. In your project, its source code, build configuration, and metadata definition are stored together in a self-contained folder. When you deploy it, this metadata creates a UIBundle record that establishes the app’s identity on the Salesforce Platform and declares which containers can host it.

This topic describes the files and metadata that make up an app, whichever framework you use.

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

1my-sfdx-project
2└── force-app/
3    └── main/
4        └── default/
5              └── uiBundles/
6                    └── myapp/
7                        ├── myapp.uibundle-meta.xml    # Salesforce metadata
8                        ├── ui-bundle.json             # Runtime configuration
9                        ├── package.json               # Application dependencies
10                        ├── src/                       # Application source code
11                        │   ├── components/            # UI components
12                        │   ├── pages/                 # Application pages
13                        │   ├── assets/                # Images, fonts, icons
14                        │   └── styles/                # Global styles
15                        └── dist/                      # Build output (generated)
16├── sfdx-project.json                                  # SFDX project configuration
17└── package.json                                       # Root workspace configuration

Each app includes framework build files that connect your app to the platform:

• vite.config.ts for React apps
• angular.json and its esbuild/ and middleware/ folders for Angular apps

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

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

The target property in this file declares which kind of Salesforce container can use this UIBundle for its UI. It doesn’t surface anything on its own. Instead, a CustomApplication or a site references the UIBundle, and that container is what appears in the Salesforce UI.

• CustomApplication lets a CustomApplication, which is an internal, employee-facing app, use the UIBundle. This is the default target if you don’t specify a value. The CustomApplication appears in the App Launcher and opens in Salesforce, rendering its UI from the UIBundle.
• Experience lets an Experience Cloud site use the UIBundle. The site appears in the Digital Experiences app and in the App Launcher, where selecting it opens the site URL in a new tab, and renders its UI from the UIBundle.

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

1<?xml version="1.0" encoding="UTF-8"?>
2<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
3    <masterLabel>myapp</masterLabel>
4    <description>A Salesforce UI Bundle.</description>
5    <isActive>true</isActive>
6    <version>1</version>
7    <target>CustomApplication</target>
8</UIBundle>

The isActive flag controls whether the deployed bundle is served, and version is a schema-version integer that starts at 1.

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.

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

1{
2  "outputDir": "dist",
3  "apiVersion": "v66.0",
4  "routing": {
5    "fileBasedRouting": true,
6    "trailingSlash": "never",
7    "fallback": "index.html",
8    "rewrites": [
9      {
10        "route": "/products/:id",
11        "target": "/product-detail.html"
12      },
13      {
14        "route": "/legacy/*",
15        "target": "/app.html"
16      }
17    ],
18    "redirects": [
19      {
20        "route": "/old-home",
21        "target": "/",
22        "statusCode": 301
23      },
24      {
25        "route": "/promo",
26        "target": "/sale",
27        "statusCode": 302
28      }
29    ]
30  }
31}

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

1{
2  "outputDir": "dist",
3  "routing": {
4    "trailingSlash": "never",
5    "fallback": "index.html"
6  }
7}

When you create an app, you choose an internal or an external template, which provides the necessary UIBundle project structure along with the related metadata that differs by use case. The template names differ by framework—for example, reactinternalapp and reactexternalapp for React, or angularinternalapp and angularexternalapp for Angular. For the full list of templates and the generate commands, see Generate an App from a Template.

Use an internal template to create internal-facing apps for employees signing in with their Salesforce credentials.

Projects based on an internal 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 app, such as c__myapp.

When a CustomApplication references the UIBundle through its uiBundle field, and the UIBundle’s target is set to CustomApplication in the .uibundle-meta.xml file, the CustomApplication appears in the App Launcher and renders its UI from the UIBundle.

1my-sfdx-project/
2└── force-app/main/default/
3    ├── uiBundles/
4    │   └── myinternalapp/
5    │       ├── myinternalapp.uibundle-meta.xml  # target: CustomApplication
6    │       ├── ui-bundle.json
7    │       └── src/
8    └── applications/
9        └── MyInternalApp.app-meta.xml           # CustomApplication metadata

Use an external 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, and authentication.

Projects based on an external 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 Multi-Framework app.
• The appSpace property refers to the related app. Make sure that the value uses the format NamespacePrefix__DeveloperName (for example, MyNamespace__MyWebApp or c__MyWebApp for orgs without a registered namespace).

1my-sfdx-project/
2└── force-app/main/default/
3    ├── uiBundles/
4    │   └── myexternalapp/
5    │       ├── myexternalapp.uibundle-meta.xml  # target: Experience
6    │       ├── ui-bundle.json
7    │       └── src/
8    ├── digitalExperienceConfigs/                # Site configuration
9    ├── digitalExperiences/                      # Site content
10    ├── networks/                                # Experience Cloud site
11    └── sites/                                   # CustomSite metadata

• Generate an App from a Template
• Manage Your App and Grant User Access
• Metadata API Developer Guide: UIBundle
• Salesforce DX Project Structure and Source Format

j

Salesforce Multi-Framework Overview

Get Started

Set Up Your Org

Quick Start: Build and Run Your First App

Generate an App from a Template

Project Structure and Metadata

Build with Agentic Coding Tools

Preview and Run Your App Locally

Style Your Apps

Integrate Agentforce Conversation Client

Access Salesforce Data and Platform Capabilities

Test, Deploy, and Distribute Your App