lumio dev

Start the development server with hot-reload and a Lumio sandbox environment.

Usage

lumio dev [--port <port>]

What it does

1. Starts a Vite dev server for each target surface defined in lumio.config.json
2. Opens a Lumio sandbox — a browser window that simulates the host environment (dashboard editor, OBS layer, or interactive page)
3. Watches for file changes and hot-reloads the affected surfaces
4. Connects to the Lumio API for real storage, events, and server function execution

Example

cd my-extension
pnpm install
lumio dev

 Lumio Dev Server
 Extension: Sports Scoreboard (88b2478a...)
 Surfaces: editor, layer

 editor   → http://localhost:3005/editor
 layer    → http://localhost:3005/layer

 Sandbox: http://localhost:3005
 Press Ctrl+C to stop

Sandbox features

The sandbox simulates the host environment with these features:

Feature	Description
Mock events	Send test events (twitch:follower, twitch:subscribe, etc.) via the sandbox UI
Storage panel	View and edit useExtensionStorage() values in real time
Surface switching	Switch between editor, layer, and interactive views
Real server functions	Server functions run against the actual staging Lumio API
Console forwarding	console.log output from the extension appears in the terminal

Options

Flag	Default	Description
--port <port>	3005	Port for the dev server
--no-open	—	Don't automatically open the sandbox in the browser

Hot reload

File changes trigger automatic hot-reload:

• src/*.tsx changes — instant hot module replacement (HMR), no full page reload
• server/*.ts changes — server functions re-bundle and restart
• lumio.config.json changes — dev server restarts

Testing events

Use the Events panel in the sandbox to fire test events:

[Sandbox] Events panel:
  twitch:follower    → [Fire]  userName: "TestViewer"
  twitch:subscribe   → [Fire]  tier: "1000", months: 3
  spotify:track      → [Fire]  title: "Lo-Fi Beats", artist: "ChilledCow"
  chat:message       → [Fire]  message: "Hello world!"

Click Fire to trigger the event and see your extension react in real time.

Using a specific environment

The dev server connects to the staging Lumio API by default. To connect to a local API instance:

LUMIO_API_URL=http://localhost:8080 lumio dev