# Lumio Extension Platform > Build widgets, overlays, bot modules, integrations, and themes for the > Lumio streaming platform. Extensions run sandboxed in iframes, communicate > via @zaflun/lumio-protocol, and can persist data through server functions. > > npm packages: @zaflun/lumio-sdk (components + hooks), @zaflun/lumio-cli > (dev toolchain), @zaflun/lumio-protocol (wire format), > @zaflun/lumio-extension-types (TypeScript types) - [Lumio Extension Platform](https://developers.lumio.vision/): Build widgets, overlays, bot modules, integrations, and themes for the Lumio streaming platform. Extensions run sandb... ## Getting Started - [Overview](https://developers.lumio.vision/getting-started/overview): Lumio Extensions are sandboxed applications that run inside the Lumio platform. They use React for UI, communicate wi... - [Becoming a Developer](https://developers.lumio.vision/getting-started/becoming-a-developer): To build and publish extensions on Lumio, you need an approved developer profile. This page walks through the applica... - [Quickstart](https://developers.lumio.vision/getting-started/quickstart): Build and run your first Lumio extension in 5 minutes. - [Prerequisites](https://developers.lumio.vision/getting-started/prerequisites): You should be comfortable with: - [Project Structure](https://developers.lumio.vision/getting-started/project-structure): A Lumio extension project has this layout: ## Surfaces - [Surfaces Overview](https://developers.lumio.vision/surfaces/overview): Extensions can render on three surfaces. Each surface is an independent React app that calls `Lumio.render()` with a ... - [Editor Panel](https://developers.lumio.vision/surfaces/editor-panel): The editor surface renders in the dashboard overlay editor sidebar. It is the primary configuration UI for your exten... - [Layer](https://developers.lumio.vision/surfaces/layer): The layer surface renders inside Browser Sources as a **transparent overlay** on the stream. It displays visual eleme... - [Interactive Page](https://developers.lumio.vision/surfaces/interactive-page): The interactive surface renders on a **standalone web page** at `/ext/\{slug\}` where viewers can interact with your ... - [Shared Storage](https://developers.lumio.vision/surfaces/shared-storage): All three surfaces share `useExtensionStorage()`. When any surface writes to storage, all other surfaces receive the ... ## SDK — Hooks - [useLumioConfig](https://developers.lumio.vision/sdk/hooks/use-lumio-config): Read and write the extension's user-configurable settings as defined in `config_schema` in `lumio.config.json`. Confi... - [useLumioEvent](https://developers.lumio.vision/sdk/hooks/use-lumio-event): Subscribe to a live stream event type. Returns the most recent event of that type, or `null` if no event has been rec... - [useLumioAction](https://developers.lumio.vision/sdk/hooks/use-lumio-action): Execute a Lumio service action — a named operation on the host platform such as sending a chat message, changing an O... - [useLumioSound](https://developers.lumio.vision/sdk/hooks/use-lumio-sound): Control sound playback in browser sources from an extension. Sounds must exist in the account's sound library — eithe... - [useExtensionStorage](https://developers.lumio.vision/sdk/hooks/use-extension-storage): Read and write the extension's shared key-value storage. Changes are persisted to the database and broadcast to all o... - [useLumioTheme](https://developers.lumio.vision/sdk/hooks/use-lumio-theme): Read the current Lumio theme (dark, light, or a custom theme). Use this to adapt your extension's appearance to match... - [useIconPicker](https://developers.lumio.vision/sdk/hooks/use-icon-picker): Headless hook for building custom icon picker UIs. Manages dialog open/close state and selection. - [useLumioIdentity](https://developers.lumio.vision/sdk/hooks/use-lumio-identity): Access the current user and account context — who is viewing this surface, what account they belong to, and what role... - [useQuery](https://developers.lumio.vision/sdk/hooks/use-query): Call a server-side query function and return its result. The query runs once on mount and can be manually refetched. - [useMutation](https://developers.lumio.vision/sdk/hooks/use-mutation): Call a server-side mutation or action function. Returns both a synchronous (`mutate`) and an async (`mutateAsync`) in... - [Bot Module Context](https://developers.lumio.vision/sdk/hooks/bot-module-context): The `BotModuleContext` object is passed as the first argument (`ctx`) to every bot module handler. It provides access... ## SDK — Components - [Layout Components](https://developers.lumio.vision/sdk/components/layout): Layout components control the arrangement and grouping of other components. They do not render visible content themse... - [Input Components](https://developers.lumio.vision/sdk/components/inputs): Input components are fully interactive on the **editor** and **interactive** surfaces. On the **layer** surface, they... - [Display Components](https://developers.lumio.vision/sdk/components/display): Display components render content — text, images, and other read-only visual elements. They work on all three surfaces. - [IconPicker](https://developers.lumio.vision/sdk/components/icon-picker): A universal icon picker for extension config panels. Lets users select from Lucide icons, Unicode emojis, platform em... - [Editor Components](https://developers.lumio.vision/sdk/components/editor): Editor components build settings UIs for `editor.tsx` and `designer.tsx` surfaces. They serialize via the Worker Reco... ## SDK - [Rendering](https://developers.lumio.vision/sdk/rendering): Every extension entry point must call `Lumio.render()` to mount the React component tree. This is the only way to dis... ## Server Functions - [Server Functions Overview](https://developers.lumio.vision/server-functions/overview): Server functions are optional server-side logic that runs on the Lumio API. They let extensions persist structured da... - [Schema](https://developers.lumio.vision/server-functions/schema): Define your extension's database tables in `server/schema.ts` using `defineSchema` and `defineTable` from `@zaflun/lu... - [Declarative Functions](https://developers.lumio.vision/server-functions/declarative): Declarative server functions are defined with `queryRows`, `insertRow`, `patchRow`, and `deleteRow`. They translate d... - [Handler-based Functions](https://developers.lumio.vision/server-functions/handler-based): Handler-based server functions use `query()`, `mutation()`, and `action()`. They run JavaScript inside a V8 isolate w... - [Storage Scoping](https://developers.lumio.vision/server-functions/storage-scoping): Each table in your extension's schema can be scoped to control which installations share the same data. The scope is ... - [Auth and Scopes](https://developers.lumio.vision/server-functions/auth-and-scopes): Server functions can inspect the identity of the caller and restrict access based on surface, role, or authentication... - [External APIs](https://developers.lumio.vision/server-functions/external-apis): Handler-based `action()` functions can call external HTTP APIs using `ctx.fetch()`. All outbound requests are restric... - [Secrets](https://developers.lumio.vision/server-functions/secrets): Secrets let you store sensitive values — API keys, tokens, passwords — that your extension needs to call external ser... - [Real-time Updates](https://developers.lumio.vision/server-functions/realtime): Extensions receive real-time updates via WebSocket when storage or server-side state changes. ## Configuration - [lumio.config.json Reference](https://developers.lumio.vision/config/lumio-config): The manifest file at the root of every extension project. It defines the extension's identity, capabilities, and dist... - [Targets](https://developers.lumio.vision/config/targets): The `targets` field in `lumio.config.json` declares which surfaces your extension renders on. Only listed targets are... - [Permissions](https://developers.lumio.vision/config/permissions): Extensions that need to trigger Lumio actions (send chat messages, control OBS scenes, emit events) must declare the ... - [Egress](https://developers.lumio.vision/config/egress): The `egress` field in `lumio.config.json` controls which external hosts your extension's server actions can make HTTP... - [Pricing](https://developers.lumio.vision/config/pricing): The `pricing` field in `lumio.config.json` controls how your extension is monetized in the Lumio Extension Store. - [Triggers](https://developers.lumio.vision/config/triggers): Trigger configuration reference for bot module extensions — commands, keywords, patterns, events, and timers. ## CLI - [Install](https://developers.lumio.vision/cli/install): npm install -g @zaflun/lumio-cli - [lumio login](https://developers.lumio.vision/cli/login): Authenticate with your Lumio account. Credentials are stored in `~/.lumio/credentials` and reused automatically for s... - [lumio init](https://developers.lumio.vision/cli/init): Create a new extension project. Runs an interactive wizard that registers the extension with Lumio (generating an Ext... - [lumio dev](https://developers.lumio.vision/cli/dev): Start the development server with hot-reload and a Lumio sandbox environment. - [lumio build](https://developers.lumio.vision/cli/build): Build the extension bundle for deployment. Produces optimized client bundles for each surface and a source archive. - [lumio deploy](https://developers.lumio.vision/cli/deploy): Upload a built extension bundle to Lumio as a new version. The version starts in `draft` status and must go through t... - [lumio status](https://developers.lumio.vision/cli/status): Show the review status of your extension's latest deployed version. - [lumio logs](https://developers.lumio.vision/cli/logs): Stream server function logs in real time (or fetch historical logs). Useful for debugging production server functions. ## Publishing - [Store Listing](https://developers.lumio.vision/publishing/store-listing): The store listing is the public face of your extension in the Lumio Extension Store. It consists of a name, descripti... - [Review Process](https://developers.lumio.vision/publishing/review-process): Every extension version must pass an admin review before it can be published in the Lumio Extension Store. The review... - [Publishing Updates](https://developers.lumio.vision/publishing/updates): When you release a new version of your extension, the update behavior depends on whether the version is marked as bre... - [Visibility](https://developers.lumio.vision/publishing/visibility): The `visibility` field controls who can discover and install your extension. - [Monetization](https://developers.lumio.vision/publishing/monetization): Lumio supports two paid pricing models for extensions: one-time purchase and monthly subscription. - [Developer Verification](https://developers.lumio.vision/publishing/verification): Developer verification is required to publish paid extensions (`one_time` or `subscription` pricing). It establishes ... - [Testing Phase](https://developers.lumio.vision/publishing/testing-phase): After an admin approves your extension for testing, it enters the `testing` status. During this phase, you can invite... - [Submission Wizard](https://developers.lumio.vision/publishing/submission-wizard): After deploying a new version with `lumio deploy`, you submit it for review via the **submission wizard** in the exte... ## Teams - [Teams Overview](https://developers.lumio.vision/teams/overview): Developer teams let multiple people collaborate on extensions under a shared identity. A team has its own name, slug,... - [Roles & Permissions](https://developers.lumio.vision/teams/roles-and-permissions): Teams use a full RBAC (role-based access control) system. Every team member is assigned a role, and each role grants ... ## Automation Nodes - [Automation Nodes Overview](https://developers.lumio.vision/automation-nodes/overview): Build custom automation nodes for the Lumio visual Automation Builder. - [Action Nodes](https://developers.lumio.vision/automation-nodes/action-nodes): Build action nodes that perform work when an automation runs. - [Trigger Nodes](https://developers.lumio.vision/automation-nodes/trigger-nodes): Build trigger nodes that start automations from external events. - [Logic Nodes](https://developers.lumio.vision/automation-nodes/logic-nodes): Build logic nodes that branch automation flows based on conditions. - [Config Panel](https://developers.lumio.vision/automation-nodes/config-panel): Build a custom React config panel for your automation node. - [Testing](https://developers.lumio.vision/automation-nodes/testing): Test automation nodes locally with the CLI dev server. ## Account - [Extension ID & Namespace](https://developers.lumio.vision/account/extension-id): Every extension published on Lumio has a globally unique identifier and a namespace that forms the root of all storag... - [Limits & Quotas](https://developers.lumio.vision/account/limits): Lumio enforces per-account and per-extension limits to ensure fair resource usage across the platform. This page list... - [Security & API Keys](https://developers.lumio.vision/account/security): Your Lumio account uses user API keys for programmatic access — to the CLI, CI/CD pipelines, and the Developer REST A... - [Payout Settings](https://developers.lumio.vision/account/payout-settings): Payout settings control how and when Lumio transfers your revenue share to you. You must complete [developer verifica... ## Examples - [Hello World](https://developers.lumio.vision/examples/hello-world): The minimal Lumio extension — a static text overlay. Use this to verify your local dev setup is working before buildi... - [Sports Scoreboard](https://developers.lumio.vision/examples/scoreboard): A live sports scoreboard overlay that fetches current game scores from the ESPN API. Demonstrates server functions, e... - [Interactive Poll](https://developers.lumio.vision/examples/challenge-rules): An interactive poll widget that lets the streamer create polls from the editor panel, lets chat viewers vote via the ... - [Chat Overlay](https://developers.lumio.vision/examples/chat-game): A scrolling chat display overlay that shows messages from all connected platforms in real time. Demonstrates `useLumi... - [Alert Box](https://developers.lumio.vision/examples/custom-alerts): A Twitch follower alert that plays an animated notification when a new follower arrives. Demonstrates `useLumioEvent`... - [Loyalty Points](https://developers.lumio.vision/examples/loyalty-points): A complete bot module with points, gambling, keyword hype counter, sub welcome, and timed reminders. - [Clip Logger](https://developers.lumio.vision/examples/clip-logger): A bot module that detects Twitch clip URLs via regex pattern, stores them, and provides a !clips command. - [Chat Moderation](https://developers.lumio.vision/examples/chat-moderation): A bot module with a moderate() handler, link blocklist, and timeout escalation. - [Twitch Rewards Bot](https://developers.lumio.vision/examples/twitch-rewards-bot): A bot module that handles Twitch Channel Points reward redemptions. - [YouTube Member Bot](https://developers.lumio.vision/examples/youtube-member-bot): A bot module that welcomes YouTube members and handles Super Chat events. - [Kick Follow Bot](https://developers.lumio.vision/examples/kick-follow-bot): A bot module that handles Kick follow events with streak tracking. - [Discord Moderation Bot](https://developers.lumio.vision/examples/discord-moderation-bot): A bot module with Discord slash commands /warn and /mute, keyword auto-mod, and member welcome. - [Cross-Platform Stats Bot](https://developers.lumio.vision/examples/cross-platform-bot): A bot module that tracks chat stats across Twitch, YouTube, and Kick simultaneously. ## API Reference - [Developer REST API](https://developers.lumio.vision/api-reference/protocol): The Lumio Developer REST API allows you to manage extensions, versions, and installs programmatically. It is intended... - [SDK Client Reference](https://developers.lumio.vision/api-reference/sdk-client): Complete reference for `@zaflun/lumio-sdk` — the client-side library used in `editor.tsx`, `layer.tsx`, and `interact... - [SDK Server Reference](https://developers.lumio.vision/api-reference/sdk-server): Complete reference for `@zaflun/lumio-sdk/server` — the server-side library used in `server/functions.ts`. - [CLI Reference](https://developers.lumio.vision/api-reference/cli): Quick-reference table and flag reference for the `lumio` CLI. - [TypeScript Types](https://developers.lumio.vision/api-reference/types): Complete TypeScript type reference for the Lumio Developer SDK and Developer REST API. ## Guides - [Debugging](https://developers.lumio.vision/guides/debugging): This guide covers common debugging techniques for Lumio extension development, from local dev server issues to produc... - [Testing Extensions](https://developers.lumio.vision/guides/testing): Lumio extensions are React applications with server functions. This guide covers unit testing components, testing ser... - [Migration Guide](https://developers.lumio.vision/guides/migration): This page documents breaking changes between SDK major versions and the steps to migrate existing extensions. - [Best Practices](https://developers.lumio.vision/guides/best-practices): Guidelines for building reliable, performant, and review-friendly Lumio extensions. - [Sandbox Architecture](https://developers.lumio.vision/guides/sandbox-architecture): How Lumio isolates extension code using a 3-layer iframe + Worker model. - [AI Assistant](https://developers.lumio.vision/guides/ai-assistant): Two ways to give your AI coding assistant full Lumio SDK context: - [Bot Modules](https://developers.lumio.vision/guides/bot-modules): Build custom chat commands, keyword responders, event handlers, and moderation modules as Lumio extensions. - [Bot Module Local Development](https://developers.lumio.vision/guides/bot-module-local-dev): Use the CLI chat simulator and single-handler runner to test bot modules locally. - [Bot Module Security](https://developers.lumio.vision/guides/bot-module-security): Security model for bot modules — V8 isolation, rate limits, permission tiers, audit log, and kill switch. - [Bot Module Updates](https://developers.lumio.vision/guides/bot-module-updates): How extension updates preserve user overrides, migrate config, and sync triggers. - [Discord Slash Commands](https://developers.lumio.vision/guides/discord-slash-commands): How bot module commands become Discord slash commands, with discord_options and registration flow. - [Cache & Background Jobs](https://developers.lumio.vision/guides/cache-and-defer): Use ctx.cache for fast temporary storage and ctx.defer() for background work after handler return. - [Error Reporting](https://developers.lumio.vision/guides/error-reporting): Anonymized production error reports for extension developers — what data is visible, what is stripped, and how to debug.