webOS Studio - VS Code Extension

webOS Studio is an Microsoft Visual Studio Code (VS Code) extension for webOS. Using this extension, developers easily start to make webOS apps/services (web app, Enact app, JS service).

Key features are as follows:

  • Managing the lifecyle of webOS apps and services
  • Managing connected webOS devices and emulators
  • Providing many convenience features for webOS development
  • Running ESLint on Enact apps

How to Install

To install the extension, launch VS Code and do the following steps:

  1. Navigate to View > Extensions.
  2. Search for webOS Studio in the search bar.
  3. Click the Install button.
Installation steps for webOS Studio

Then you will see the webos Studio icon in Activity Bar icon in Activity Bar.

Once the installation is completed, see the Setup Guide | VS Code marketplace

UI Overview

Click the webos Studio icon in Activity Bar icon to see the user interface of the extension:

User Interface of the webOS Studio

ComponentDescription
Apps in workspaceLists apps in the workspace. The workspace of webOS Studio is different from that of VS Code. For more details, refer to webOS Studio | VS Code marketplace.
Known deviceLists the known devices registed by webOS Studio or CLI.

By default, a dummy emulator device is listed in the view. This device requires VirtualBox emulator on your computer. See the Emulator Manager section.
Package managerManages SDKs for webOS app developement.
Emulator ManagerLists installed images in VirtualBox Emulator.
SimulatorOnly for webOS TV.
Quick LauncherLists links to webOS Studio documents and tools.
Command PaletteEnters and executes various commands. (Shortcut: Ctrl + Shift + P)
Notification AreaShows notification messages for completion, errors, and more about the extension.

Basic Usage

This section explains a typical development flow of webOS apps and services using this extension.

Adding Known Devices

  1. Click the + button in the KNOWN DEVICE view.

    Add the known device

  2. Enter the name, IP, port, and username of your webOS device.

    Add the known device

  3. (Optional) Set the device as the default device. Actions that don’t specify the target device will be performed on the default device.

    Set the default device

Creating an App/Service

First, let’s create an app for webOS device. Do one of the following:

  • Click the + button in the APPS IN WORKSPACE view.
  • Execute webOS: Create ProjectWizard in the Command Palette.

Then the Project Wizard window will be displayed.

Creating an app

First Screen

ItemDescription
webOS ProductA target platform which this app/service will be installed on.
API VersionAn API level of webOS. Different versions of the webOS platform support different levels of APIs. See API Levels.

Second Screen

ItemDescription
TemplatewebOS Studio provides multiple template for webOS apps/services. Supported templates are as follows:
  • Basic Web App: A basic web app for webOS.
  • Hosted Web App: A hosted web app.
  • Web App Info: Configuration file for a web app (appinfo.json). See appinfo.json.
  • JS Service: A JavaScript service for webOS. This service MUST be packaged and installed with an app.
  • JS Service Info: Configuration files for a JS service (services.json and package.json). See services.json.
  • Sandstone, Moonstone: Enact apps with the Sandstone library or the Moonstone library. For more details about Enact apps, visit the Enact website.

webos-service Library

webos-service library is a library for using webOS components on JS services or Enact apps. This library is for legacy webOS OSE devices (for version 1.x.x).

To use the library, do one of the following:

  • Check the Yes button for Add webOS library.

    Add LS2 APIs to projects

  • Install it in the APP IN WORKSPACE view.

    Install webos-service library using NPM

Editing the Source Code

Now it’s time to implement your own features on the created apps or services.

Editing with Auto-Completion

webOS Studio supports a powerful content-assist feature called Auto-Completion. Auto-completion includes API suggestions and automatically completes method names, helping users implement webOS features more easily.

For more details about the auto-completion feature, see Auto-Completion.

Auto Completion Example

Previewing with Auto Reload

While you editing an app, You can preview the app UI before installing it.

In the APPS IN WORKSPACE view,

  1. Right-click the app.
  2. Click Preview Application.
  3. The preview of the app is automatically launched on the IDE.

Start the app preview

In the preview, you can modify the source codes and check the results instantly.

Changing colors using auto reload

Packaging / Installing / Launching

Typical steps to install webOS apps are as follows:

  1. Package the source code into an .ipk file.
  2. Install the IPK file.
  3. Launch the installed app.

The above three steps are triggered sequentially by clicking the Run App button in the APPS IN WORKSPACE view.

The run app button

Then, enter the information about the app. If you use the default information, just press the Enter key.

Package, install, and launch an app

Note

A JavaScript service is always packaged with an app. If you want to install a JavaScript service, select the service in the Service directory to pack with App step.

Select JS service

You can uninstall the apps in the KNOWN DEVICE view.

Uninstall the app

Or You can uninstall the app manually using the appInstallService API or webOS CLI.

Debugging

You can debug apps or services that are installed on the known devices. Supported types are as follows:

  • Web app
  • Enact app
  • JavaScript service

Prerequisites

  • Apps or services are installed on target devices
    • The target devices or emulators should be registered as the known devices.
  • (For inspector debugging) Chromium-based browser

Start a Debugging Session - App

  1. Right-click an installed app.

  2. Click Debug on.

  3. Click inspector or VS Code.

    1. [inspector]

      Enter a path for the browser executable.

      Enter a broweser executable path

      Then the debugging session will be activated in the browser.

      Debugging an app with browser

    2. [VS Code]

      The DEBUG CONSOLE panel will be activated automatically. In the panel, you can check the console messages from the app or service.

      Start a debugging session

      In the debugging session, you can set breakpoints, check variables, callstack, etc.

      Debugging example

Start a Debugging Session - Service

  1. Right-click an installed service.

  2. Click Debug on.

  3. Click inspector or VS Code.

    1. [inspector]

      1. After clicking the inspector button, a URL for the debugging session will be displayed in the OUTPUT panel. Copy the URL.

        URL for debugging service

      2. Open your browser and go to chrome://inspect. Configure the URL as follows:

        Configure the debugging URL

        Note
        Microsoft Edge browser automatically redirects chrome://inspect to edge://inspect.
      3. Click inspect.

        Click the inspect button

        This opens a new window for the debugging session.

        Debugging a service with browser

    2. [VS Code]

      The DEBUG CONSOLE panel will be activated automatically.

      Debugging a service with IDE

Note

Every time you restart a debug session, the packaged app will be closed on the target device. If you want to check the behavior of the app, relaunch the app manually.

Relaunch the app

Trouble Shooting Guide for Debugging

Q) The Run and Debug view is not opened

Click View > Open View... > Run and Debug.

Q) The debugging session is not launched

Close all running apps on the webOS device and re-try to click Debug on.

Q) (Very rare to happen) A notification says the debugging session is already activated

If you get this notification, even when all debug sessions are closed, restart the VS Code and try to start a debugging session again.

Running ESLint on the Enact App

ESLint statically analyzes files for potential errors (or warnings) and helps enforce a common coding style. For more information, check ESLint Configurations.

In the APPS IN WORKSPACE view,

  1. Right-click the React app.
  2. Click Run Lint.

The PROBLEMS panel shows the result messages.

Run lint

To clean the Lint messages from the panel, click Clear Lint.

Clear lint

Other Features

Auto-Completion

Auto-completion suggests a list of available LS2 APIs based on the project’s API level.

Auto completion Overview

Features

Key features are as follows:

  • Auto-completing API strings using the Tab key
  • Providing a list of available LS2 APIs (services, methods, and parameters)
  • Providing descriptions for each LS2 API
  • Providing links to API documentation webpages

How to Use

To use auto-completion, type one of the following trigger strings:

  • luna://
  • new LS2Request

luna://

To start the auto-completion feature, enter one of the following strings:

  • luna://
  • 'luna://'
  • "luna://"

Auto completion for LS2 APIs

You can print the list of available services, methods, and parameters using the following trigger strings:

ItemTrigger String
Serviceluna://
MethodEnter the / right after luna://<service name>
ParameterCtrl + Space after luna://<service>/<method>

new LS2Request

Type new LS2Request to use Enact webos Library. Using Ctrl + Space, you can use the auto-completion.

Auto completion for LS2Request

Trouble Shooting Guide for Auto-Completion

Q) Auto-completing using the `Tab` key doesn't work

Check the Tab Completion setting is on.

Enable the tab completion feature
Q) I entered the trigger strings, but it didn't show a list

To use auto-completion, .webosstudio.config file should be in the project root folder. This file contains information about the API level.

This file will be automatically generated if you generate a project using the Project Wizard. In case you don't have this file, generate the file as follows:

  1. Type luna://.

    This invokes a notification to generate the config file. Click Yes.

    Notification to generated the config file
  2. Then a Quick Pick pop-up appears at the top of VS Code.

    Enter the API level you want.

    Quick pick pop-up for selecting the API level
  3. The config file is generated in your project folder. You can check the API level in the config file.

    Generated config file

Package Manager

Package Manager manages SDKs for webOS app developement. Users can install and uninstall SDKs with a simple click.

Package manager UI

In order to launch the Package Manager on Windows, VS Code has to be opened in administrator permission. On Mac and Ubuntu, the system prompts you for the root user password during component installation.

When a user runs the Package Manager for the first time, a pop-up message for selecting directory will show up. Once the directory is set, all SDKs are installed in this directory.

Configuring a directory for Package Manager

Some SDKs require prerequisite software before they are installed. In this case, Package Manager checks if the software is installed. If not, it will download, extract, and install the software. A list of prerequisites for each SDK is shown in the next section.

Prerequisites

The following table lists software prerequisites for each SDK.

SDKPrerequisites
webOS OSE Emulator
Workflow DesignerNone
Resource MonitorNone

Emulator Manager

You can manage webOS emulator (VirtualBox) images in VS Code. By default, any webOS emulator images installed in VirtualBox are listed in the EMULATOR MANAGER view.

Prerequisites

  • VirtualBox must be installed on your computer. (Supported version: 6.1 or higher)
  • webOS emulator image (.vmdk) is required. For how to make the image, refer to Emulator User Guide.
  • Emulator Launcher is required. Execute webOS: Install Emulator Launcher in the Command Palette (Ctrl + Shift + P).

How to Manage Emulator Images

  1. Click the + button in the EMULATOR MANAGER view.

    Add emulator button

  2. Fill in the input form. For the other system requirements, refer to Emulator User Guide.

    Emulator input form

  3. Click Add Instance and the created instance is listed in the EMULATOR MANAGER view.

    Added emulator instance

  4. Click the Run App button (triangle) to run the emulator. This action will launch a new VirtualBox window.

    Start the emulator instance

    To stop or close an emulator instance, close the running VirtualBox window.

Note
  • Multiple emulator instances cannot use the same VMDK file.
  • Only one emulator instance can be launched at the same time.
  • When deleting an emulator instance, the associated VMDK file is also DELETED. Make sure that the VMDK file is safely backed up.

IPK Analyzer

You can analyze the file size of the app or services in the IPK file.

  1. Open the Command Palette (Ctrl + Shift + P) and type webOS: IPK Analyzer.

  2. Click Import IPK.

  3. Choose the IPK file to analyze. After the file is loaded, you can see the following screen:

    IPK analyzer

  4. Click the Compare IPK button to load another IPK. (For example, the older version of the original file)

    Compare IPK files

Process Log

webOS Studio has many internal utility commands including ares-cli, enact-cli, and VirtualBox utility. In the OUTPUT panel, you can check the output logs of these commands. Developers might find out helpful information to debug their apps or services.

Process log in the output panel

Resource Monitor

The Resource Monitor tracks and visualizes system and memory usage, CPU consumption, and so on. This enables developers to test their apps or services and identify resource consumption trends and patterns.

Note
Resource Monitor embeds InfluxDB and Grafana into VS Code. This guide only introduces how to use few user scenarios of them through the com.webos.serivce.sdkagent API. For more details about InfluxDB and Grafana, refer to each website.

Default Dashboard

Developers can set the default dashboad for the Resource Monitor, which is called Provisioned Dashboard.

  1. In the PACKAGE MANAGER view, click the icon to install the resource monitor.

    Install resource monitor

  2. To launch the Resource Monitor, do the one of the followings:

    • In the QUICK LAUNCHER view, click the Resource Monitoring.
    • Execute webOS OSE: Launch Resource Monitoring in the Command Palatte.
    Note
    You can have multiple Resource Monitor tabs running at once.

    Then the resource monitor tab will be launched.

    Launch the resource monitor

  3. Go to your webOS device, stop the Resource Monitor running (if you’ve run it before.)

    luna-send -f -n 1 luna://com.webos.service.sdkagent/collector/stop '{}'
    
  4. Connect the Resource Monitor using the following command. Replace <HOST_IP> into your computer’s IP address.

    luna-send -f -n 1 luna://com.webos.service.sdkagent/collector/setConfig '{"agent":{"flush_interval":"5s","interval":"5s"},"outputs.influxdb":{"urls": ["http://<HOST_IP>:8086"]}}'
    
  5. Set up the dashboard.

    luna-send -f -n 1 luna://com.webos.service.sdkagent/collector/setConfig '{"webOS.webProcessSize":{"enabled":true}}'
    
    luna-send -f -n 1 luna://com.webos.service.sdkagent/collector/setConfig '{"webOS.processMonitoring":{"enabled":true,"process_name":["com.webos.app.home","com.webos.app.notification","com.webos.app.volume","com.webos.service.sdkagent"]}}'
    
  6. Start the monitoring.

    luna-send -f -n 1 luna://com.webos.service.sdkagent/collector/restart '{}'
    

    Then the Resource Monitor shows the default dashboard as follows:

    Running the resource monitor

    Note
    The default (provisioned) dashboard appears only on the first tab. From the second tab, you’ll see Grafana’s default UI.

Add a New Dashboard

Grafana provides many user-made dashboards. These dashboards can be searched and imported using the Grafana UI.

  1. Hover on the Dashboards menu and click Import.

    Go to the import menu

  2. Enter the ID of dashboards and click the Load button.
    Recommeded IDs are 928, 5955, 2381.

    search the dashboard

  3. Select the data source and click the Import button.

    Import the dashboard

Trouble Shooting Guide for Resource Monitor

Q) I followed the guide above, but I don't see the dashboard.

Go to the Settings, check the webosose > Resource Monitoring: Provisioned Dashboard setting is on.

Enable the provisioned dashboard
Q) My service is crashed, and not worked.

Restart the webOS device and follow the above steps again.

FAQs

Q. What are the different types of projects that can be created in the extension?

A. Supported types are as follows:

Type

Description

Basic Web App

Creates a sample HTML "hello world" app that has a standard webOS OSE file system.

Hosted Web App

Creates a sample HTML app with an example to show some external page in-app with standard webOS OSE file system.

Web App Info

A dummy web app, which contains only appinfo file to use with any already developed HTML app.

Basic Enact App

Creates an enact Sample app as per selected template.

JS Service

A simple JS service with a service file.

JS Service Info

A dummy service info directory, which is used for reference of standard service information.

Q. What is "Add webOS library", and when is it needed?

A.This feature adds webos-service library to your project. The webos-service library is to call LS2 APIs in the app/service. But we strongly recommend using WebOSServiceBridge API instead of webos-service library.

Q. I have not added any device in the KNOWN DEVICE view, yet I can see the device named emulator.

A. By default, emulator is added in the KNOWN DEVICE view. This emulator is running on the local system. If you an emulator instance is not already set up, go to the EMULATOR MANAGER view and add the emulator instance.

Q. Getting an error while packaging the app, when my folder path contains special characters.

A. Workspace path and name should not contain any escape or special characters, it can trigger errors on add, package, install operations.

Q. How to resolve errors in Notification Area?

A. A list of the errors:

Error

Description

ERROR! Failed to get the device list.

Some dependent packages are not available on the local system.

To resolve this issue, install the packages either manually or by clicking Yes when prompted (if you previously closed the prompt without installing, click the refresh button in the KNOWN DEVICE view to get prompted again).

ERROR! Failed to list the applications installed on <device>

The device is not running.

ERROR! Failed to list the applications running on <device>

The device is not running.

ERROR! Please check IP address or port of <device>

The device is not reachable.

ERROR! Unable to find the Virtual Box

Update the environment path variable to point to the VirtualBox installation directory.

ERROR! Packaging App Failed. Details As follows: <errMsg>

Failed to package the app due to one of the following:

  • Check the ID format. Only lowercase letters(a-z), digits(0-9), minus signs, and periods are allowed.
  • Check the version format. It should be something like 1.0.0.
  • Only a valid app can be packaged. Make sure the directory includes 'appinfo.json'.
  • Some dependent resources (such as images, libraries, and modules) that are required for the project are missing. Add manually or through the npm command.

Contents