Preview Components with Local Dev

Local Dev for Experience Cloud Lightning Web Runtime (LWR) sites 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, you can develop your Lightning web components (LWCs) in a real-time preview of your Lightning app or Experience Cloud 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.

Starting in Spring '25, Local Dev is generally available for Lightning apps. For Experience Cloud LWR sites, this feature is available as an open beta.

Use Local Dev to run a preview of the following types of Salesforce projects.

Lightning Experience apps (desktop and Salesforce mobile app)
LWR Sites for Experience Cloud

You can enable Local Dev for scratch orgs, too.

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

Before you can run a real-time preview of your app or site, follow these steps to install and enable Local Dev.

Install the Salesforce CLI. (For now, this feature is only available through the Salesforce command-line interface (CLI).)
Install the Local Dev Plugin.
Enable Local Dev.

If you want to use Local Dev for a production org, install the feature using either of these CLI commands:

If you have a scratch or sandbox org with an upcoming release, install the prerelease instance of the package with this command:

Before you can use Local Dev for an app or site, you have to enable it for your Salesforce org. If you try to use Local Dev without first enabling it in Setup, the tool fails on the CLI.

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

To turn on this feature for your production or sandbox org, from Setup, in the Quick Find box, enter Local Dev and then select Local Dev. Select Enable Local Dev 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:

After you save your changes to project-scratch-def.json, scratch orgs created with that JSON file will have Local Dev enabled.

There are different commands for previewing a Lightning app and an Experience Cloud LWR site. To make sure you have the latest version of the CLI command, run sf update before you start a Local Dev instance.

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.

You can preview a Lightning app in a desktop or Salesforce mobile app (iOS or Andorid) environment.

In the CLI, run sf lightning dev app with the following flags as needed. Starting in Spring '25, if you forget to set a needed flag, don't worry: the CLI will prompt you to select a value for it from a list of valid options.

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 spaces in it, 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.

For more information about using Local Dev to run your Lightning App in a mobile environment, see Using Salesforce Mobile App Simulators and Emulators.

When you run sf lightning dev site on the CLI, Local Dev automatically generates and downloads a static bundle based on the current state of your site. You can only preview an Experience site in a desktop environment with Local Dev.

For now, you have to publish your Experience site before you can run a site preview using Local Dev.

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 spaces in it, wrap the name in quotes. Example: To run Local Dev for a site named SDO - Consumer, run `--name "SDO - Consumer"`
`--flags-dir`	Optional	Import flag values from a directory.
`--get-latest`	Optional	The `sf lightning dev site` command caches a version of your Experience site on your machine. This cached version is used whenever you subsequently run the Local Dev `site` command again. To update the local cache with the latest version of your site from your org, such as to preview recent Experience Builder changes, add the `--get-latest` flag to your command.

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

With Local Dev, you can efficiently test your Lightning app in different mobile environments. Before you can use this feature, you have to install and configure necessary mobile development tools. You only have to complete this setup process once on your machine.

Mac users can run an iOS simulator for Local Dev using Xcode. If you don’t already have Xcode, install it from the Mac App Store and complete the initial setup process. In Xcode, make sure you download iOS mobile device simulators to use with Local Dev.

If you're having trouble with your Xcode installation, refer to Mobile and Offline Developer Guide: Set Up Xcode.

To run your app in an iOS simulator using Local Dev, set --device-type to ios in your CLI command: sf lightning dev app --device-type ios.

You can also run your app in an Android emulator using Android Studio. If you don't already have this tool, install it from developer.android.com/studio. For a walkthrough of how to install Android Studio for Salesforce projects, see Mobile and Offline Developer Guide: Set Up Android Studio.

To run your app in an Android emulator using Local Dev, set --device-type to android in your CLI command: sf lightning dev app --device-type android.

Don't worry about manually installing the Salesforce mobile app on your simulator or emulator virtual device. When you run the Local Dev CLI command, the CLI will prompt you to install the Salesforce mobile app if needed, like this:

Terminal output for the Local Dev iOS simulator command that automatically prompts you to install the Salesforce mobile app, if needed.

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

Starting in Spring '25, Local Dev detects new or deleted files in your components and automatically updates your preview. For example, if you move shared functions into a component's Util.js file, your app preview automatically updates to reflect the code you added.

Previously, if you added or deleted a file in an existing component, you had to redeploy the component and restart the Local Dev server to see that change in your 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.

Starting in Spring '25, Local Dev no longer saves a copy of your built app or site in your static resources folder. Previously, automatically saved builds counted toward the 250 MB org static resource limit.

You can't preview Landing Pages with Local Dev.