Mobile and Offline Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Mobile App Development with Lightning Web Components and LWC Offline
Create Mobile-Ready Components
Use Mobile Device Features in Mobile Apps
Offline Considerations and Limitations
Offline Environment Details
Use Salesforce Features While Offline
Development Tools and Processes
Understand the Mobile Development Cycle
Set Up Your Development Environment
Preview Components on Mobile
Mobile Development Preview Environments
Preview from the Command Line
Preview from VS Code
Preview in the Salesforce Mobile App
Preview in Custom Mobile Apps
Validate Lightning Web Components for Offline Use
Develop Offline-Ready LWCs with the LWC Offline Test Harness
Debug Mobile Components
Customize the Offline Experience for the Salesforce Mobile App
Quick Start Tutorials
PDF

Preview Components from the Command Line

After you’ve installed the Mobile Extensions plug-in and set up Xcode and Android Studio, you can launch previews directly from the command line. As you code, mobile previews immediately reflect your changes.
The force:lightning:lwc:preview command supports two sets of parameters: three basic parameters and four advanced parameters. Every call requires the first two basic parameters and, optionally, the third. Advanced parameters let you designate and configure a custom app to host the preview.
sf force:lightning:lwc:preview -p <platform_name> -n <component_name> 
    [-t <target_virtual_device_name>] [-a browser|<app_identifier>] 
    [-d <project_dir>] [-f <preview_config_file>] [--confighelp]
Basic Parameters
  • -n, --componentname:

    Name of your component.

  • -p, --platform:

    Mobile platform to use for the preview. Can be either Android or iOS (not case sensitive).

  • (Optional) -t, --target:

    Name of a target virtual device. This device is the iOS simulator or Android emulator configuration that hosts the preview. You can pass the name of a new or an existing device. If you enter a name that’s not recognized by the selected platform, this command creates the device using the system default configuration. If omitted, the command launches the default virtual device for the given platform. See the Managing Devices section.

Advanced Parameters
  • (Optional) -a, --targetapp

    Target app for the preview. Acceptable values are browser, which means the default mobile browser, or an app ID. Defaults to browser.

  • (Optional) -d, --projectdir

    Root directory of the CLI project. Defaults to the current working directory.

  • (Optional) -f, --configfile

    File named mobile-apps.json that specifies extended configuration options for the preview. If you pass an app ID to --targetapp, you’re required to provide this file. Use the -f parameter to specify a custom path to this file. This path can be relative (to the project’s working directory) or absolute.

  • (Optional) --confighelp

    Displays the schema of the extended configuration file.

Here’s a macOS example of a basic call. The name of your component is helloWorld, and you’re developing it in the ~/Projects/helloWorld/ directory.

  1. In a Terminal window, cd to the directory of your Lightning Web Components project.
    cd ~/Projects/helloWorld/
  2. Start the Lightning Web Components server.
    sf force:lightning:lwc:start
    Because the server is a synchronous process, this window doesn’t accept further command input until the server is stopped.
  3. Leaving the server running, open a second Terminal window or Windows command prompt in your project directory, and enter this command:
    sf force:lightning:lwc:preview -p Android -n HelloWorld -t "Pixel XL API 29"

Launching the virtual device can take a few seconds. After it has booted, the Mobile Extensions plug-in presents your component in the device’s default browser. You can inspect and interact with your component. If you change visual aspects of your component’s code, the simulator immediately reflects those changes without requiring a manual refresh.

Managing Devices

To manage devices:
  • iOS: Use the Devices and Simulators tool in Xcode.
  • Android: Use the Android Virtual Device (AVD) Manager.
To see the list of supported virtual devices in your environment, use the device:list command:
  • iOS:
    sf force:lightning:local:device:list ios
  • Android:
    sf force:lightning:local:device:list android
Use this command only after your development environment is fully configured and operational. Virtual device images are required to match or exceed system requirements for Mobile Extensions. In addition, the following scopes can limit the number of devices shown in the list.
iOS:
Devices must run iOS or iPadOS.
Android:
No known limitations.

Here are a few tips on how the device list works.

  • If you enter a name that doesn’t match an existing virtual device, Mobile Extensions creates a device with that name.
  • Android virtual devices created by Mobile Extensions are based on the latest SDK level and use Google APIs.

Configuring a Native Mobile App to Host Previews

You can use the force:lightning:lwc:preview command to launch a preview in an iOS or Android native mobile app that you provide. No Salesforce-specific requirements apply to these custom native apps. Your app simply must provide some means of displaying Lightning web components.

To launch previews in your custom app, the Mobile Extensions plug-in requires information about the app’s identity and its access points. You specify the following properties in the JSON configuration file you specified in the --configfile parameter.
id
iOS
The app’s ID in reverse-DNS format.
Android
The app’s ID in the format supported by the Android Debug Bridge (adb) shell. For example, here’s the format that the adb start command accepts:
adb shell am start -n com.package.name/com.package.name.ActivityName
name
The app’s “friendly” name. Salesforce VS Code Extensions use this name to identify the app.
get_app_bundle (Optional)

Name of a Node.js or TypeScript module that provides configuration for installing the app on the target device or emulator.

This module must expose a run() method that returns the path to the app bundle as a String. If this path is relative rather than absolute, Mobile Extensions calculates the path relative to the configuration file. This module is also responsible for providing any implementation details that allow access to the app bundle.

If the get_app_bundle argument is present, Mobile Extensions calls the run command before launching the preview. If omitted, Mobile Extensions assumes that the bundle is already installed on the target device or emulator.

activity (Android only)
The class name of the app’s main activity in a format that supports launching the app from the Android Debug Bridge (adb) shell. For example, here’s the format that the adb start command accepts:
adb shell am start -n com.package.name/com.package.name.ActivityName
In your configuration file, you use .ActivityName (including the leading period.)
launch_arguments (Optional)
An array of objects specifying arguments required for launching the app. Each object contains one argument’s name and value. Each argument name and argument value is expressed as a name-value pair.
preview_server_enabled (Optional)
Indicates whether the native app requires a local development server for previewing a component. If false (default value), the preview command proceeds without checking for a running server instance. If true, before beginning the preview the command checks for a running server instance. If this check fails, the command returns an error and prompts the user to start the server before rerunning the command.
Properties other than launch_arguments are simple name-value string pairs. Here’s a sample configuration file.
{
  "apps": {
    "ios": [
      {
        "id": "com.salesforce.mobiletooling.lwctestapp",
        "name": "LWC Test App",
        "get_app_bundle": "configure_ios_test_app.ts",
        "launch_arguments": [
          { "name": "ShowDebugInfoToggleButton", "value": "true" },
          { "name": "username", "value": "Astro" }
        ],
        "preview_server_enabled": true
      }
    ],
    "android": [
      {
        "id": "com.salesforce.mobiletooling.lwctestapp",
        "name": "LWC Test App",
        "get_app_bundle": "configure_android_test_app.ts",
        "activity": ".MainActivity",
        "launch_arguments": [
          { "name": "ShowDebugInfoToggleButton", "value": "true" },
          { "name": "username", "value": "Astro" }
        ],
        "preview_server_enabled": true
      }
    ]
  }
}
You can access the schema for this file at /src/cli/commands/force/lightning/lwc/previewConfigurationSchema.json in the forcedotcom/lwc-dev-mobile GitHub repo.