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.
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:
If you want to use Local Dev for a production org, run either one 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 scratch 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 totrue
, like this:
There are different commands for previewing a Lightning app and an Experience Cloud LWR site. You can run your preview in a desktop or Salesforce mobile app (iOS or Android) environment. To make sure you have the latest version of the CLI command, run sf update
.
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. Starting in Spring '25, if you forget to set a mandatory flag, the CLI prompts 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 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:
--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. |
Starting in Spring '25, you can run Local Dev without publishing your site first. Now, 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.
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. - 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.