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.
Three surfaces
Every extension can render on up to three surfaces:
| Surface | File | Where it renders | Purpose |
|---|---|---|---|
| Editor | src/editor.tsx | Dashboard overlay editor sidebar | Configuration UI, settings panels |
| Layer | src/layer.tsx | OBS Browser Source (transparent) | Visual overlay in the stream |
| Interactive | src/interactive.tsx | Standalone page (/ext/\{slug\}) | Audience interaction (votes, games) |
All three surfaces share the same storage via useExtensionStorage() — a change in the editor propagates to the layer in real time.
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.