@salesforce/lwc-dev-server

Salesforce CLI plugin for Local Development (Beta)

Usage no npm install needed!

<script type="module">
  import salesforceLwcDevServer from 'https://cdn.skypack.dev/@salesforce/lwc-dev-server';
</script>

README

Local Development

CircleCI Build status codecov MIT license npm (scoped) Commitizen friendly

The Local Development Server is a Salesforce CLI plugin that configures and runs a Lightning Web Components-enabled server on your computer. Now you can develop Lightning Web Component modules and see live changes without publishing your components to an org.

Note: This feature is in beta and has been released early so we can collect your feedback. It may contain significant problems, undergo major changes, or be discontinued. If you encounter any problems, or want to request an enhancement, open a GitHub issue. The use of this feature is governed by the Salesforce.com Program Agreement.

Setup

System Requirements

  • Developer Hub-enabled org
  • Most recent stable version of Chrome, Firefox, Safari, or Edge web browser
  • Windows—Windows 7 (64-bit and 32-bit) or later
  • Mac—macOS 10.11 or later
  • Linux—Ubuntu 14.0.4 or later
  • Salesforce CLI
  • Java 8

To develop Lightning web components, use your favorite code editor. We recommend using Visual Studio Code because its Salesforce Extensions for VS Code provide powerful features for development on Lightning Platform.

Installation

  1. Open a new terminal window and run the following command to install the local development server.
sfdx plugins:install @salesforce/lwc-dev-server
  1. Check for updates to the local development server.
sfdx plugins:update
  1. Navigate to your SFDX project, or clone one that has Lightning web components. In this example, we are using lwc-recipes.
git clone git@github.com:trailheadapps/lwc-recipes.git
  1. If you're not in the the lwc-recipes root directory already, cd into it.
cd lwc-recipes

  1. Add the .localdevserver folder in your SFDX project to your .gitignore file. Do not modify files inside of this folder.

  2. Authorize a Developer Hub (Dev Hub) by following the steps in Enable Dev Hub In Your Org in the Salesforce DX Developer Guide. A Dev Hub is the main Salesforce org that you and your team use to create and manage your scratch orgs, temporary environments for developing on the Salesforce platform. You need the Dev Hub to create a scratch org in a later step.

  3. Following the instructions in the Salesforce DX Developer Guide, log in using your Dev Hub credentials. Running the following command spawns a login window in your browser.

sfdx force:auth:web:login -d -a myhuborg
  1. In local development, requests to Lightning Data Service and Apex go to scratch orgs, similar to how they go to your production org. To create a scratch org, run this command from the command line.
sfdx force:org:create -s -f config/project-scratch-def.json -a "LWC"

“LWC” is an alias for the scratch org that you can use in other Salesforce CLI commands.

To create a scratch org, specify a scratch org definition file. This example uses the scratch org definition file, project-scratch-def.json that is included in lwc-recipes. For other projects, create your own. For more information, see the instructions for Create Scratch Orgs in the Salesforce DX Developer Guide.

  1. Start the server.
sfdx force:lightning:lwc:start
  1. View the server at http://localhost:3333/.

For more information on local development commands, view the local development documentation by running sfdx force:lightning:lwc: --help.

Troubleshooting

$ sfdx force:lightning:lwc:start
Starting LWC Local Development.
    Dev Hub Org: mydevhub
    Scratch Org: undefined - We can't find an active scratch org for this Dev Hub. Create one by following the steps in Create Scratch Orgs in the Salesforce DX Developer Guide (https://sfdc.co/cuuVX4) or the Local Development Server Getting Started.

If you see this error, make sure that you authenticate to your Dev Hub and create a scratch org.

Working With Modules and Components

Supported Modules

The local development server supports the following modules. Modules refer to @salesforce modules and modules imported without @salesforce, like lightning/empApi. For more information about how these modules work with Lightning web components, see @salesforce Modules in the Lightning Web Components Developer Guide.

Module Name Local Development Behavior
@salesforce/resourceUrl Import static resources into your Salesforce org using the structure: import <resourceName> from '@salesforce/resourceUrl'. Static resources are copied and served from the SFDX project location on your filesystem to the local development server.
@salesforce/label Custom Labels are resolved from the SFDX project directory labels/CustomLabels.labels-meta.xml. The local development server displays a placeholder for labels that it either can't find or that you created in Setup but didn't sync to your local filesystem. The placeholder looks like this: {unknown label: foo}. In the case where your label is not in your org, SFDX returns an error when you push your code.
@salesforce/apex Apex requests are proxied to your scratch org.
@salesforce/schema Follows the same behavior described in the Lightning Web Components Developer Guide reference.

Partially Supported Modules

These modules work with the local development server, but behave differently from how they do in a production org.

Module Name Local Development Behavior
@salesforce/i18n The locale is set to US/English locale. For local development, all imports from @salesforce/i18n are hardcoded to return values that are similar to what you would see in the en-US locale in production.
@salesforce/user You can include @salesforce/user when working in local development. User ID is not supported, and local development assigns it a value of undefined. The value of isGuest always returns true.

Unsupported Modules

The local development server throws an error if you try to preview any components that use these modules.

  • @salesforce/contentAssetUrl
  • @salesforce/apexContinuation

Considerations

  • The local development server supports Lightning web components only. It does not support Aura components.
  • Don't connect to a production Salesforce org with the local development server. Local development uses data in real time. If you authenticate to a production org, then you will modify or overwrite data in production.
  • You can't specify or change attribute values for your components on the component preview page. Components render with their default attribute values. For example, let's say you're writing a clock component. To view the component, the clock needs to know your timezone, which requires setting a timezone attribute. We recommend setting a default timezone in the code. If you can't specify a default value, create a wrapper component that creates the clock and sets the proper attributes. To prevent confusion, make sure to give your wrapper component a name that clarifies it is for testing purposes only.
  • SLDS CSS and icons are included with the local development plugin, and are automatically included on every page. If you notice differences between how some SLDS classes render in local development versus how they do on your Salesforce instance, they may be running different versions. In the beta release, you cannot modify the version of SLDS, and it won't sync with the version you're running on your instance.
  • Flexipages aren't supported.
  • Locker is not supported.
  • Salesforce Standard Design Tokens and Custom Tokens in CSS files aren't supported.

Running from Source

With linking you can run the latest code from source.

Clone this repo:

git clone git@github.com:forcedotcom/lwc-dev-server.git

Build the project:

cd lwc-dev-server
yarn install && yarn build

From within the lwc-dev-server directory, link it with the Salesforce CLI:

sfdx plugins:link

You can verify that it was linked propery by running sfdx plugins:

$ sfdx plugins
@salesforce/ui-api 0.1.2
lwc-dev-server 1.0.0 (link) /Users/nmcwilliams/dev/lwc-dev-server
├─ @oclif/plugin-update 1.3.9 (link) /Users/nmcwilliams/dev/lwc-dev-server/node_modules/@oclif/plugin-update
└─ @oclif/plugin-help 2.1.6 (link) /Users/nmcwilliams/dev/lwc-dev-server/node_modules/@oclif/plugin-help

salesforcedx 45.13.1-0 (release)
├─ force-language-services 45.9.1-0
└─ salesforce-alm 45.15.1-1

Note, you can also unlink the plugins by running the unlink command from the same directory:

sfdx plugins:unlink

Contributing

See CONTRIBUTING.md