Flutter for webOS

Flutter-webOS is an extension to the Flutter SDK that enables the development of Flutter apps for webOS using the Flutter framework. It provides all the necessary tools and libraries to build, package, and run Flutter apps on webOS-based devices. This document provides guidance on how to set up the environment to create, build, and run a Flutter app on webOS TV using the flutter-webOS toolchain.

Requirements

Host environment

Flutter for webOS development is supported on Linux (Ubuntu) only.

Target device

Flutter for webOS supports webOS TV starting from webOS 26 Re:New.

Developer Mode must be enabled on the TV before deploying apps. For more information, see Developer Mode App

Set up the environment

This section covers the initial setup required for your development machine. Setting up your environment involves three stages: installing system-level dependencies, installing the flutter-webOS SDK and NDK, and verifying the installation.

1. Set up the Linux environment

Install the required system packages on Ubuntu and configure Git (version 2.23 or higher).

2. Install the flutter-webOS SDK

Clone the flutter-webOS repository and add the CLI to your PATH. Then install the webOS NDK (Native Development Kit) and configure the required environment variables.

3. Verify the installation

Run `flutter-webos doctor -v` to confirm all components are configured correctly, then pre-cache engine artifacts with `flutter-webos precache`.

For detailed instructions, refer to the Set up the environment guide.

Set up the device

This section covers how to connect your webOS TV as a development target. Once your SDK is ready, you need to enable Developer Mode on the TV and register it so that flutter-webOS can deploy and communicate with the device over the network.

1. Enable Developer Mode on the TV

Enable Developer Mode on your webOS TV, turn on the Key Server, and note your passphrase.

2. Add the device

Register your TV as a custom device by entering its ID, IP address, and port. Then retrieve the SSH key from the TV using your passphrase.

3. Verify the connection

Confirm that the device appears and is reachable with `flutter-webos devices`.

For detailed instructions, refer to the Set up the device guide.

Develop an app

Once your environment is ready, the development workflow consists of creating a project, building an installable `.ipk` package, and running it on your TV.

1. Create a project

Create a new Flutter project with webOS platform support using `flutter-webos create`.

2. Build and package

Build an installable `.ipk` package from your project directory. flutter-webos supports three build modes: `--debug`, `--profile`, and `--release`.

3. Install and run the app

Deploy the app to your registered device with `flutter-webos run`.

4. Debugging

Run the app in debug mode using the `--debug` flag.

For detailed instructions, refer to the Develop an app guide.

webOS TV Integration

Luna Service

webOS TV uses Luna Service as its IPC (Inter-Process Communication) mechanism. Luna Service allows apps to interact with system services such as network, media, settings, and input. Using the webos_service_bridge plugin, you can call Luna Service APIs from your Flutter app.

ACG (Access Control Group)

webOS TV enforces access control on all Luna Service API calls through ACG. Each Luna Service method belongs to one or more ACG groups, and your app must declare the required groups to be granted access. Without the correct ACG setup, Luna Service calls will be rejected at runtime regardless of the implementation.

For detailed instructions, refer to the ACG guide.

Plugins

flutter-webOS provides a set of webOS-specific plugins that give your Flutter app access to native webOS TV capabilities. These plugins act as a bridge between Flutter and the webOS platform, enabling features that are not available through the standard Flutter SDK.

For detailed instructions, refer to the Plugins guide.