Overview
Lumio Extensions are sandboxed applications that run inside the Lumio platform. They use React for UI, communicate with the host via postMessage, and can define server-side functions for data persistence and external API calls.
Two surfaces
Every extension can render on up to two surfaces:
| Surface | File | Where it renders | Purpose |
|---|---|---|---|
| Editor | src/editor.tsx | Dashboard overlay editor sidebar | Configuration UI, settings panels |
| Layer | src/layer.tsx | Browser Source (transparent) | Visual overlay in the stream |
Both surfaces share the same storage via useExtensionStorage() - a change in the editor propagates to the layer in real time.
There is no viewer page. Viewers interact through chat commands and channel point rewards handled by a bot module - see Viewer Input.
Server functions
Extensions can optionally define server-side functions that run on the Lumio API:
- Declarative -
queryRows,insertRow,patchRow,deleteRowtranspile directly to SQL (no JS runtime overhead) - Handler-based -
query(),mutation(),action()run in a V8 isolate sandbox with memory and CPU limits
Server functions get their own isolated PostgreSQL schema (ext_\{extension_id\}) and Redis namespace (lumio:ext:\{extension_id\}:\{account_id\}:*).
Security model
Extensions are sandboxed at 9 layers: admin code review, DB isolation, iframe sandbox, egress allowlist, rate limiting, V8 sandbox, token scoping, Redis isolation, and secret isolation. See Security for details.
SDK
The @zaflun/lumio-sdk package provides React hooks and components:
- 14 components - layout, input, and display primitives
- 10 hooks - storage, events, actions, identity, config, theme, queries, mutations
- Server exports - schema definitions, declarative CRUD, handler-based functions
Distribution
Extensions are distributed through the Lumio Extension Store. The publishing workflow is: lumio deploy (draft) → submission wizard → admin review → testing phase → publish.