Preview Components with Local Dev (Beta)

Local Dev is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

USER PERMISSIONS NEEDED
To enable Local Dev for an org:	View Setup and Customize Application

With Local Dev (Beta), you can develop your Lightning web components (LWCs) in a real-time preview of your Lightning app or Experience Cloud Lightning Web Runtime (LWR) site. The preview automatically updates when you save changes to your source code, so you can iterate faster on your LWCs without deploying code or manually refreshing the preview in your browser.

Migrate to the new Local Dev experience before we eventually deprecate the LWC Local Development Server, which has limited testing and previewing capabilities.

Local Dev is available for users in Winter '25 sandboxes as an open beta, and it's turned off by default. You can also enable Local Dev for scratch orgs.

With Local Dev, you can run a preview of the following types of Salesforce projects.

Lightning Experience
Salesforce mobile app
LWR Sites for Experience Cloud
- We recommend enabling Local Dev for publicly accessible sites only.

For now, this feature is only available through the Salesforce command-line interface (CLI). To run a real-time preview for your app or site:

Install the Salesforce CLI.
Install the Local Dev Plugin
Enable Local Dev.

In your terminal, run this CLI command for your project.

Before you can use Local Dev for an app or site, you have to enable it for your Salesforce sandbox org or scratch org.

For now, Local Dev is available for Winter '25 sandboxes only.

To turn on this beta feature for your sandbox org, from Setup, in the Quick Find box, enter Local Dev and then select Local Dev. Select Enable Local Dev (Beta) to turn on the feature for all org users.

To enable Local Dev for your scratch org, complete these steps.

In your SFDX project, open the file config/project-scratch-def.json.
In the settings section of the file, add the key "enableLightningPreviewPref" and set it to true, like this:

To preview a Lightning app, run this command in your terminal:

To preview an Experience Cloud LWR site, run this command:

When you run these commands, you have to include the --target-org flag and set it to a valid org username or alias. For more information, see Preview a Lightning App or Preview an Experience Cloud LWR Site.

Optionally, you can add other flags to customize your local app or site preview. For example, set a value for the --device-type flag to run your preview in a desktop or Salesforce mobile app (iOS or Android) environment. To learn more about flags for these commands, see the following sections about previewing Lightning apps and Experience Cloud LWR sites.

To successfully run Local Dev CLI commands, you must have an lwc folder in your project that contains LWCs. This folder is typically nested in the force-app/main/default directory.

In the CLI, run sf lightning dev app with the following flags as needed.

Flag	Required/Optional	Description
`-o`, `--target-org`	Required	The username or alias of the target org for the preview. Not required if you already set the `target-org` configuration variable. Example:`--target-org myOrg`
`-n`, `--name`	Optional	The name of the Lightning Experience app you want to preview. If your site name has whitespaces, wrap the name in quotes. Example: To run Local Dev for an app named SDO - Consumer, run `--name "SDO - Consumer"`
`-t`, `--device-type`	Optional	The type of device to display the app preview. It accepts only one of these options: `desktop` `ios` `android` Example: `--device-type desktop`
`-i`, `--device-id`	Optional	If you set `--device-type` to `ios` or `android`, you can choose the ID of the mobile device to display the preview. The default value is the ID of the first available mobile device. Example: `--device-id "iPhone 15 Pro Max"`
`--flags-dir`	Optional	Import flag values from a directory.

Before you can run Local Dev for an Experience Cloud LWR site, you have to finish these setup steps:

After Local Dev is enabled for your org, publish your Experience Cloud LWR site.
Set your site's base path to /. To learn how to configure site paths, see Salesforce Help: Add a Custom URL.

This is a beta-only limitation. We're working on removing this step for the GA release of Local Dev.

Then, in the CLI, run sf lightning dev site with the following flags as needed.

Flag	Required/Optional	Description
`-o`, `--target-org`	Required	The username or alias of the target org for the preview. Not required if you already set the `target-org` configuration variable. Example: `--target-org myOrg`
`-n`, `--name`	Optional	The name of the Experience Cloud LWR site you want to preview. If your site name has whitespaces, wrap the name in quotes. Example: To run To run Local Dev for a site named SDO - Consumer, run `--name "SDO - Consumer"`
`--flags-dir`	Optional	Import flag values from a directory.

Be aware of these considerations and limitations for working with Local Dev.

With Local Dev, you can efficiently test your project in different mobile environments by running your Lightning app in an iOS simulator or an Android emulator. Before you can use this feature, you have to follow these steps to install and configure necessary mobile development tools. You only have to complete this process once on your machine.

Install Xcode and iOS Simulators
Install Android Studio and Android Emulators
Download iOS and Android Mobile App Packages
Install iOS and Android Virtual Device Builds from the Mobile App Packages in step 3.

You can run Salesforce on any supported simulator or emulator provided with these environments.

When you edit local files with Local Dev enabled, your LWCs automatically reflect only the following changes in your app or site preview:

Automatically Loaded Change	Example
Basic HTML revisions	Changing component attributes, like `title="Hello"` to `title="Goodbye"`
New reference to a component	Adding `<lightning-button></lightning-button>` to your markup
Basic CSS revisions	Changing `--slds-c-card-heading-font-weight: 100px;` to `--slds-c-card-heading-font-weight: 500px;`
Importing a new CSS-only component	Adding a `cssLibrary` component that contains only a CSS file and a configuration file, like in Share CSS Style Rules
JavaScript changes in component methods that don't affect the component's public API	Using a new event handler in a template or changing existing event handler logic.

To apply any other local changes to your app or site preview, follow these steps:

Deploy the changes to your org using the project deploy start command.
If you're previewing an Experience Cloud LWR site, you also have to republish your site in Experience Builder.
Finally, restart the Local Dev server to see the updated app or site preview in your browser.

For example, these changes do not automatically load in your Local Dev preview. To see these changes in your Local Dev preview, you have to follow the steps for manually loading local changes.

Adding a new @api property or method to a component class
Making changes related to wire adapters, such as configuration updates, importing a new wire adapter, adding @wire to a property, and changing a GraphQL query
Importing new @salesforce scoped modules
Updating your .js-meta.xml file
Revising a service component library

If you add a new file to an existing component, you have to restart the Local Dev server to see that change in your app or site preview.

Local Dev automatically updates your preview with most local changes to files ending in .js, .html, and .css. If you edit a component file of any other type — like .js-meta.xml — you have to deploy the component to see those changes in your local preview.

Local Dev only lets you preview LWCs. You can't use it to test Aura components in your app or site preview.

A static resource in your app or site can be up to 5 MB in size. An org can have up to 250 MB of static resources.

When you publish an app or site with Local Dev enabled, a copy of your built app or site is saved in your static resources folder. If you exceed the static resources limit and Local Dev isn't working for your app or site, contact your Salesforce representative.

You can't preview Landing Pages with Local Dev.