How to Run a React App Natively on Salesforce: A 2026 Developer’s Guide

Why React on Salesforce is a Game-Changer

For years, Salesforce development forced a choice: adopt Lightning Web Components (LWC) for native features or use React and struggle with authentication, security, and "static resource" workarounds.

That barrier has vanished. With the launch of Salesforce Multi-Framework on the Agentforce 360 Platform, you can now build native Salesforce applications using React. This framework-agnostic runtime provides built-in authentication, governance, and security. Currently in Open Beta, it allows developers to utilize modern tooling like Vite and Tailwind CSS directly within the Salesforce ecosystem.

Prerequisites for Salesforce React Development

Before scaffolding your project, ensure your environment meets these requirements:

• Org Type: A Salesforce Sandbox or Scratch Org (Default language: English).
• Salesforce CLI: Version v2.130.7 or later (includes the required UI Bundle plugin).
• Tooling: VS Code + Salesforce Extension Pack.
• Environment: Node.js v18+ and npm.

Pro Tip: Run sf --version to check your CLI version. If you are behind, run sf update immediately to unlock the UI Bundle commands.

Step 1: Enable Salesforce Multi-Framework (Beta)

To build React apps natively, you must manually toggle the runtime in your org.

1. Navigate to Setup.
2. Search for Salesforce Multi-Framework.
3. Select React Development with Salesforce Multi-Framework (Beta).
4. Click Enable Beta.

Warning: This is a permanent, one-way activation. Always use a dedicated scratch org or "throwaway" sandbox to avoid altering your primary development environment.

Step 2: Scaffold Your React Project with UI Bundles

The Salesforce CLI now treats React apps as a native metadata type: the UIBundle. Use the following commands to generate your starter app:

# Install the Salesforce UI Bundle plugin
sf plugins install @salesforce/plugin-ui-bundle-dev

# Generate a new Salesforce DX project
sf template generate project --name my-react-project

# Navigate into the project directory
cd my-react-project

# Generate a React UI Bundle using the "reactbasic" template
sf template generate ui-bundle \
  --name myreactapp \
  --directory "./force-app/main/default/uiBundles" \
  --template reactbasic

The Modern Tech Stack

By using the -t reactbasic flag, Salesforce scaffolds a professional-grade development environment:

Vite: For ultra-fast bundling.

Tailwind CSS & shadcn/ui: For modern, accessible styling.

Vitest: For unit testing.

Your React app lives inside force-app/main/default/uiBundles/. It is not a standalone project; it deploys alongside your Apex and LWC metadata.

Step 3: Local Development and Authentication

One of the biggest benefits of Multi-Framework is the Local Proxy. You no longer need to manage OAuth tokens or CORS headers manually.

# Navigate to the app directory
cd force-app/main/default/uiBundles/myreactapp

# Install project dependencies
npm install

# Start the local development server
npm run dev

Navigate to localhost:5173. The dev server communicates directly with your Salesforce org using your CLI's active session.

Step 4: Fetching Data with the Salesforce Data SDK

The @salesforce/sdk-data package allows React developers to query Salesforce via GraphQL or invoke Apex methods with ease.

Example: Fetching a Contact Record

// src/pages/ContactCard.tsx

import { useEffect, useState } from 'react';
import { createDataSDK, gql } from '@salesforce/sdk-data';

const QUERY = gql`
  query GetContact {
    uiapi {
      query {
        Contact(first: 1) {
          edges {
            node {
              Name {
                value
              }
              Title {
                value
              }
              Department {
                value
              }
            }
          }
        }
      }
    }
  }
`;

type ContactData = {
  name: string;
  title: string;
  department: string;
};

export default function ContactCard() {
  const [contact, setContact] = useState<ContactData | null>(null);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const sdk = await createDataSDK();

        const response = await sdk.graphql(QUERY);

        const node =
          response.data?.uiapi?.query?.Contact?.edges?.[0]?.node;

        if (node) {
          setContact({
            name: node.Name?.value || '',
            title: node.Title?.value || '',
            department: node.Department?.value || '',
          });
        }
      } catch (error) {
        console.error('Error fetching contact:', error);
      }
    };

    fetchData();
  }, []);

  if (!contact) {
    return <p>Loading...</p>;
  }

  return (
    <div
      style={{
        border: '1px solid #ddd',
        padding: '1.5rem',
        borderRadius: '8px',
        maxWidth: '400px',
        boxShadow: '0 2px 8px rgba(0,0,0,0.08)',
      }}
    >
      <h2>{contact.name}</h2>

      <p>
        {contact.title} — {contact.department}
      </p>
    </div>
  );
}

Then register the route in src/routes.tsx:

// src/routes.tsx

import App from './App';
import ContactCard from './pages/ContactCard';

const routes = [
  {
    path: '/',
    element: <App />,
  },
  {
    path: '/contact',
    element: <ContactCard />,
  },
];

export default routes;

Key Implementation Notes:

Automatic Auth: createDataSDK() handles session management for you.

Value Property: GraphQL returns values inside a .value object (e.g., node.Name.value).

Step 5: Real-Time Iteration with Live Preview

Instead of constant deployments, use Agentforce Vibes and Live Preview in VS Code.

Open the Command Palette (Cmd+Shift+P).

Run 'SFDX: Open in Live Preview.' Select your React app to see code changes reflected instantly inside a Salesforce context.

Step 6: Deployment to Salesforce

When your app is ready for testing, build and push it to your org:

# Navigate to the app directory and build the project with Vite
npm run build

# Return to the Salesforce project root directory
cd ../../../../..

# Deploy metadata and build files to the target Salesforce org
sf project deploy start --target-org my-org

Once deployed, your app appears in the App Launcher. You can customize the name and visibility in the app’s meta XML file.

Comparison: React vs. LWC on Salesforce

Which framework should you choose? Use this breakdown for your 2026 project planning:

Feature	React (Multi-Framework)	Lightning Web Components (LWC)
Best For	Ecosystem reuse, cross-platform UI	Native Salesforce UI, Drag-and-drop
Data Access	Salesforce Data SDK (GraphQL)	@wire and Lightning Data Service
Styling	Tailwind CSS, shadcn/ui	SLDS (Salesforce Lightning Design System)
App Builder	Not yet supported (Coming 2027)	Full Drag-and-Drop support

Current Beta Limitations

Production: Not available; Sandboxes and Scratch Orgs only.

Placement: Cannot yet be used as individual components in Lightning App Builder.

Localization: Requires English as the default org language.

Looking Ahead: Micro-frontend support, allowing you to embed React components directly into existing Lightning Pages, is slated for a Spring 2027 pilot.