Build A Screen App

What Are Screen Apps?

Screen Apps are web-based applications that run across multiple platforms, including PhyOS VMs and devices, Tizen devices, and modern browsers. They provide a graphical user interface, delivering user-facing experiences that function as control panels or client interfaces for interacting with the PhyStack services and connected devices in your ecosystem.

Just like edge apps, screen apps are:

• Published and managed via your PhyStack tenant
• Deployed and configured using the Console
• Integrated with platform features, including:
  • App versioning
  • Settings schemas
  • Centralized configuration and content management
  • Real-time event collection via Signals

Common Use Cases for Screen Apps

Screen Apps are ideal for creating interactive user experiences and visual interfaces that connect to the PhyStack platform. Common applications include:

• Digital signage and content displays
• Interactive kiosks for customer engagement and self-service
• Product information displays with dynamic pricing
• Interactive wayfinding and directory systems
• Real-time dashboards displaying sensor data and device status
• Control interfaces for managing connected hardware and peripherals
• Queue management systems with live updates

How Screen Apps Work

• Runtime: Powered by modern browser engines across all supported platforms
• Deployment: Hosted and delivered by PhyStack’s app hosting service
• Flexible Stack: Often built with React + TypeScript, though any modern web framework is supported
• Offline Support: Apps and media assets work offline on compatible platforms

Apps are tightly integrated into the PhyStack ecosystem, meaning:

• Updates and content management at scale through versioning
• Event-driven UI updates using Signals and peripheral twins

Prerequisites

Official PhyStack templates and examples use React with TypeScript, offering modern tooling, strong typing, and native SDK support. This is the stack we’ll be working with throughout this tutorial.

Before you begin, make sure the following are set up and ready to go:

A PhyStack Tenant

You’ll need access to a PhyStack tenant. If you don’t yet have one, please refer to the Tenant Setup guide.

Local Development Environment with the PhyStack CLI Installed and Configured

If you haven’t set up the CLI on your machine yet, refer to the Dev Environment Setup guide.

PhyStack Simulator

The simulator is required to run your app locally during development. See the Simulator reference for setup and usage.

Step-by-Step: Creating and Publishing a Screen App

Once your environment is ready, you can create and publish your first screen app. The flow is: scaffold a project, run it locally in the simulator, register the app in your tenant, then build and publish.

1. Scaffold the Screen App Project

phy app init my-screen-app --type screen

This clones the official screen template (Vite + React + TypeScript) and patches it with your app’s name — a complete, buildable project, not an empty shell.

Install the dependencies:

cd my-screen-app
bun install

You can explore your newly created project. In the directory with the project, you will find:

• React + TypeScript project
• Inside the src directory:
  • settings/index.json: Contains the app’s default settings for local development. You can customize these settings to suit your needs, but ensure they conform to the structure defined in schema.ts.
  • schema.ts: Settings schema for your application with example settings (learn more in the Settings Schemas guide)
  • analytics-schema.ts: Analytics dashboard configuration (learn more in the Reports guide)
  • App.tsx: Main React application component with example boilerplate logic
• Other files commonly found in React projects, like package.json containing useful scripts, tsconfig.json, and more

The App.tsx file demonstrates the usage of @phystack/hub-client package for platform integration.

The component also includes example initialization of Signals for event tracking. Signals are not covered in this tutorial, but you can learn more about them in our dedicated Signals guide.

2. Run App Locally with the Simulator

Start the simulator server in a separate terminal:

phy-simulator start

Then launch the app against it:

bun run dev

This runs phy-simulator run ., which creates a local twin based on your settings from src/settings/index.json (the default path — if the file doesn’t exist, it generates defaults from schema.ts) and starts the Vite dev server. Your browser will open automatically at http://localhost:3000 with the app connected to the simulator (the #instanceId=… fragment in the URL tells the app which twin it is). Changes to your code will be reflected in real time.

For full details on simulator commands and options, see the Simulator reference.

3. Register the App in Your Tenant

phy app create my-screen-app --type screen

This registers the app definition in your tenant — a one-time step. The command is non-interactive and prints the app’s identifiers when it completes.

4. Build & Publish

bun run pub

The pub script runs your local build (typecheck, Vite production bundle, generated schemas) and then:

phy app build create my-screen-app --dir . --publish

which packages the bundle, submits the build, and publishes it as soon as it processes. Screen apps ship no container image, so there is no --push and no registry login involved.

Checkpoint

After completing this process, you’ll have:

• A working screen app project on your local machine built with React
• A new app available in your tenant for installation

Deploying the App to a Device

Now that your app is ready, the next step is to create an installation and deploy it to a browser device or a physical PhyOS device.

Create an Installation

1. Log in to console.phystack.com
2. Navigate to Apps > Developer and locate your app in the list
3. Press the Install button and provide a name for your new installation
4. After confirmation, you will be redirected to the Installation page
5. A build of your app will be created automatically as part of the installation

Connect a browser device

Browser devices provide a convenient way to test your screen app directly on your computer in an environment that simulates a real PhyStack device. This option is good for development and testing, but not intended for production deployments.

1. Navigate to the Devices tab on your Installation page
2. Press the Connect a device button
3. In the modal that appears, click Setup a new device
4. Select Web Browser as the device type
5. Open the browser URL, presented on the right
6. Enter:
   • A name for the device
   • The provisioning code displayed in the browser window
7. Confirm by pressing the Connect device button

Once successfully connected, your app will load automatically in the browser window.

For additional details on connecting devices to installations, check out this guide.

Connect a physical device

In this step, you can connect a physical device with a screen to your installation.

For an overview of supported device types, refer to our Device Setup guide.

If you don’t have a physical device ready now, the browser device from the previous section is all you need to finish this tutorial.

If you’d rather try a real PhyOS Device without physical hardware, install PhyOS in a virtual machine with the QEMU/KVM guide. Once it’s connected to your Tenant, the VM behaves like any other Device, so the steps below apply unchanged.

1. Navigate to the Devices tab on your Installation page
2. Press the Connect a device button
3. In the modal that appears, click Setup a new device
4. Choose your device type from the available options
5. Follow the setup instructions displayed on the right side of the modal
6. Enter:
   • A name for the device
   • The serial number or provisioning code shown on your device’s screen
7. Confirm by pressing the Connect device button

Once the device is successfully connected, you should see your app appear on the device screen shortly after.

If you run into issues at this stage, refer to the Troubleshoot & Debug article of the documentation.

Make Code Changes

With your app now running locally and on the device, let’s make some changes to see the development workflow in action.

Open src/App.tsx and update the <Title> text from "Phystack React App" to "Hello PhyStack!":

...
  return (
    <Container>
      <ProductInfo>
        <Logo src={logo} alt="Phystack" />
        <Title>Hello PhyStack!</Title> {/* <-- was "Phystack React App" */}
        <SettingsDisplay>
          <SettingItem>
            <Label>Product name:</Label>
            <Value>{productName}</Value>
          </SettingItem>
          <SettingItem>
            <Label>Product price:</Label>
            <Value>{productPrice}</Value>
          </SettingItem>
        </SettingsDisplay>
      </ProductInfo>
    </Container>
  );
...

After saving your changes, the app running locally will automatically update and reflect the changes in real time. If you stopped the dev session, run bun run dev again to reconnect.

Publish an Updated Version

Once your app is updated and working as expected, publish a new version and deploy it via the Console:

bun run pub

This rebuilds the production bundle and submits a new build — the build version is bumped automatically (pass --version to phy app build create if you want to control it explicitly).

Test the New Version in Console

1. Go back to your installation in the PhyStack Console
2. Open the Settings tab and press Edit settings
3. Change the value of “Product name”
4. In the Version dropdown, select the latest version that you have pushed.
5. Press Save all changes

When you access the Settings tab of your installation, you’ll see that the settings defined in your app’s schema.ts appear in the Console as an editable form.

After a few moments, your app will be redeployed to connected devices with the new version.

You should now see the newly added “Hello PhyStack!” heading and the updated product name from your settings on both the device screen and the connected browser window.

Success!

Your app is now running the updated version with modified code and updated settings.

You’ve successfully gone from creation to deployment, iteration, and production publishing, all with full integration into the PhyStack platform.

Checkpoint

After completing this part of the tutorial, you should have:

• A functional screen app running on your connected browser and PhyOS device
• An installation configured in your tenant

Next Steps

Now that your app is setup, you can:

• Create settings schema to manage your app’s configuration
• Start integrating with peripheral twins
• Use Signals to emit events and monitor edge activity