Mobile and Offline Developer Guide

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

Newer Version Available

This content describes an older version of this product. View Latest

Preview Components in Custom Mobile Apps

If you develop your own custom native apps for iOS and Android, you can adapt them to preview Lightning web components. You provide configuration for installing your app on mobile devices and implement some means of hosting the preview. At runtime, you use the advanced features of the lwc:preview command to send previews to your app.

The best way to learn about custom app previews is to study the examples at github.com/forcedotcom/LWC-Mobile-Samples. This repo contains sample native mobile apps built to host previews, and sample Lightning Web Components projects for previewing in those apps. Binding these artifacts together are the advanced parameters of the lwc:preview command.

HelloWorld: A Sample Lightning Web Component Project

The HelloWorld project in the top level of the LWC-Mobile-Samples repo is the simplest place to start. This Lightning Web Components project satisfies the lwc:preview requirements by including a JSON configuration file and mobile app bundle scripts. You can find these files in the root folder of the HelloWorld project:
  • JSON configuration file: mobile-apps.json
  • iOS bundle script file: configure_ios_test_app.ts
  • Android bundle script file: configure_android_test_app.ts
You specify the bundle script file names in the get_app_bundle pairs of mobile-apps.json.

Custom Native Sample Apps

In the apps folder of the LWC-Mobile-Samples repo, you can find the iOS and Android native apps that the HelloWorld component targets. These native apps are bare-bones projects that each add a container for Lightning web component previews to what’s essentially a template app. In iOS, the container is an instance of WKWebView. In Android, it’s a WebView object. These two classes—WKWebView and WebView—are implementation-dependent choices. For your own app, you can use whatever works best for hosting web content.

The iOS and Android apps follow the same preview flow:
  1. Parse the configuration values and launch arguments from the JSON file.
  2. Use the launch arguments to create a preview URL. If the preview_server_enabled argument is true but the launch arguments don't include a web domain and port number, configure a URL based on a local private address and default port.
  3. Instantiate a web view object.
  4. To display the preview, send the URL with component name to the web view.
This sample also adds a bonus Debug Info button that reveals the launch argument configuration.

Where Do I Place the Configuration File?

To guarantee that the plug-in finds and uses your configuration file, follow these guidelines.

  • Requirement (all cases): Name your configuration file mobile-apps.json. The plug-in doesn’t accept other configuration file names.
Command-line usage
  • Use the preview command’s optional -f and -d parameters to specify a custom location:
    • -f specifies the config file’s location. This path can be absolute or relative.
    • -d specifies the project’s root directory.
The Mobile Extensions plug-in uses these two parameters as follows.
  • If you specify -f but not -d, the plug-in uses the value of -f to determine the file’s location.
  • If you specify -f and -d, the plug-in can consider both values to determine the file’s location.
    • If -f uses a relative path, the file location is calculated starting from the directory specified by -d. If -d isn’t specified, the path is calculated against the current working directory.
    • If -f specifies an absolute path, the -d value is ignored in calculating the config file location.
Example 1
-f /../../mobile-apps.json
-d /Users/jdoe/MyProject
Result /Users/mobile-apps.json
Example 2
-f /Users/jdoe/OtherProject/mobile-apps.json
-d Not specified
Result /Users/jdoe/OtherProject/mobile-apps.json
Example 3
-f /Users/jdoe/OtherProject/mobile-apps.json
-d /Users/jdoe/MyProject
Result /Users/jdoe/OtherProject/mobile-apps.json
Example 4
-f mobile-apps.json
-d Not specified
Result <current_working_directory>/mobile-app.json

If the plug-in is unable to find the config file on the calculated path, it posts an error message showing the path that failed.

VS Code usage
In VS Code, you can’t specify a custom path for the config file. VS Code always looks for mobile-apps.json in the default root folder of the Lightning Web Components project.