Building React Apps Natively on Salesforce: A First-Build Checklist

Building a React app on Salesforce is more than uploading a JavaScript bundle. The app needs the right metadata container, data-access path, permissions and release checks. Salesforce Multi-Framework supplies the runtime; your project still needs those pieces wired together.

This is a first-build checklist for an employee-facing app. For the broader choice between Multi-Framework, external hosting and a Sites portal, see which headless approach fits a React frontend.

What must your org support?

Multi-Framework is generally available, with React and Angular supported. It requires a Hyperforce org on Summer '26 or later. Supported editions are Enterprise, Performance, Unlimited, Developer and Partner Developer; Salesforce Government Cloud and Alibaba Cloud aren’t supported.

In Setup, open Salesforce Multi-Framework Apps and check the Salesforce app domain. Internal apps also require Salesforce Edge Network, configured in My Domain. Use current Salesforce CLI and editor extensions rather than instructions written for the early beta.

Choose a sandbox or scratch org for the first build. Decide who will test the app with ordinary user permissions, not just administrator access.

Which template and metadata do you need?

Start with the current internal React app template, reactinternalapp, rather than adapting a Commerce storefront example. It provides the project structure and related metadata for an employee app. Follow Salesforce’s current template-generation guide for the CLI syntax installed on your machine.

The app lives under force-app/main/default/uiBundles/ in a Salesforce DX project. Its folder contains source code, build configuration, compiled assets, .uibundle-meta.xml and ui-bundle.json.

Two metadata pieces work together:

• The UIBundle declares a CustomApplication target.
• A CustomApplication references that bundle through its uiBundle field and makes the application available in the App Launcher.

The UIBundle target alone doesn’t put the app in the launcher. Include the generated access permission set and review what it grants before assignment.

How should you build the first data screen?

Keep the first screen narrow: list a user’s accessible records, open one record and save one permitted change. That checks the runtime, data layer and access model without building the whole application first.

Use the Salesforce Platform SDK and its Data SDK for supported GraphQL queries and mutations. Current examples use sdk.graphql.query for reads and sdk.graphql.mutate for writes, not the beta’s single GraphQL method. Handle empty results, errors and potentially undefined response data.

GraphQL requests through the SDK use the User Interface API, which enforces object permissions, field-level security, sharing and validation rules. Calls to custom Apex require a separate access-mode review; don’t assume a React screen makes every Apex operation run with the same protections.

What should you check in routing and the build?

Review the generated React build settings and confirm that ui-bundle.json points outputDir at the compiled assets. For a single-page app, Salesforce documents a routing fallback to index.html, so refreshing a nested route can resolve to the app rather than a missing file.

Build and preview through the current documented workflow, then deploy the UIBundle and related metadata together. Keep dependencies and build configuration in source control alongside the Salesforce metadata. Verify the result from the App Launcher, not only from the local development server.

Native hosting doesn’t make third-party packages risk-free. Review the dependencies you add, and test loading, focus, keyboard use and error states.

What must pass before the first release?

Use a short acceptance checklist:

• The intended user can open the app; an unassigned user can’t.
• Restricted fields and records aren’t exposed.
• Invalid writes receive an understandable error.
• Empty and large result sets remain usable.
• Refreshing a nested route works.
• A failed request doesn’t leave the screen pretending a save succeeded.
• The release includes a tested way to restore the previous working version.

Test on the actual desktop and mobile surfaces you intend to support. An app opening in the Salesforce mobile app isn’t evidence that every screen is usable there.

What changes for external apps or embedded screens?

An external template targets Experience and includes Experience Cloud site metadata. Public pages can use guest access; customers and partners who sign in need appropriate Experience Cloud licenses. You can’t edit that Multi-Framework site’s pages in Experience Builder.

For composition inside a Lightning or Experience Cloud page, embedding an internal Multi-Framework app through lightning-ui-embedding is Beta. It uses a thin LWC host and a sandboxed iframe; the React app doesn’t become an LWC.

Winter '27 supports second-generation packaging for internal apps. External-facing app packaging remains unsupported. Keep these boundaries out of assumptions about a future portal or AppExchange release.

FAQ

Is Multi-Framework React-only?

No. React and Angular are supported. This checklist uses React because that’s the app being built.

Does a UIBundle appear in the App Launcher by itself?

No. An internal app also needs CustomApplication metadata that references the bundle, plus user access.

Does the app need its own OAuth token code?

Not for supported platform data access in the Multi-Framework runtime. Salesforce handles the session; external integrations still need their own appropriate authentication.

Does native React replace LWC?

No. LWC remains suitable for integrated reusable Salesforce components. Multi-Framework suits self-contained apps using React or Angular.

Sources: Overview, org setup, project metadata, Winter '27 guide.

Book an intro call