@zaflun/lumio-sdk

The official SDK for building Lumio extensions — widgets, overlays, bot modules, integrations, and themes for live streamers.

Installation

npm install @zaflun/lumio-sdk react react-dom

Quick Start

import { Lumio, CompactView, Text, Toggle, useExtensionStorage } from "@zaflun/lumio-sdk";

function MyWidget() {
  const [storage, setStorage] = useExtensionStorage("settings", { visible: true });

  return (
    <CompactView title="My Widget">
      <Toggle
        label="Visible"
        checked={storage.visible}
        onChange={(checked) => setStorage({ ...storage, visible: checked })}
      />
      <Text content={storage.visible ? "Hello World!" : ""} />
    </CompactView>
  );
}

Lumio.render(<MyWidget />, { target: "editor" });

What's included

14 UI Components

Layout: Box, VStack, HStack, CompactView, List Display: Text, Image Input: Button, Toggle, TextField, TextArea, NumberField, Dropdown, Slider Animation: Animated (with 22 built-in presets)

10 Hooks

| Hook | Purpose | |------|---------| | useExtensionStorage() | Persistent key-value storage synced across surfaces | | useVisionState() | Per-key state with real-time sync | | useExtensionContext() | Extension metadata (ID, target, overlay) | | useLumioEvent() | Subscribe to platform events (49 event types) | | useLumioConfig() | Read/write extension config | | useLumioTheme() | Active overlay/widget theme (colors, fonts) | | useLumioIdentity() | Current user/account context | | useLumioAction() | Trigger platform actions (21 action types) | | useQuery() | Call server query functions | | useMutation() | Call server mutation functions |

Server Functions (@zaflun/lumio-sdk/server)

import { defineSchema, defineTable, v, queryRows, insertRow } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  scores: defineTable({
    player: v.string(),
    points: v.number(),
  }).storage("instance"),
});

export const getScores = queryRows("scores");
export const addScore = insertRow("scores", { player: arg("player"), points: 0 });

Animation

import { Animated, useAnimation, defineKeyframes } from "@zaflun/lumio-sdk";

// Built-in presets: fadeIn, slideUp, zoomIn, bounce, pulse, ...
<Animated in="fadeIn" duration={500}>
  <Text content="Hello!" />
</Animated>

Custom Fonts

import { localFont } from "@zaflun/lumio-sdk";

const scoreFont = localFont({
  src: "./fonts/Orbitron-Bold.woff2",
  family: "Orbitron",
  fallback: ["sans-serif"],
});

Three Surfaces

| Surface | File | Where it renders | |---------|------|-----------------| | editor | src/editor.tsx | Dashboard sidebar panel | | layer | src/layer.tsx | OBS overlay (transparent) | | interactive | src/interactive.tsx | Audience page |

All surfaces share storage — changes in the editor propagate to the overlay in real time.

Security

Extensions run in a sandboxed Web Worker with zero DOM access. A custom React reconciler serializes the component tree to JSON, which the host renders. Extension code cannot access cookies, JWT tokens, localStorage, or any host resources.

Documentation

• Getting Started
• Component Reference
• Server Functions
• Full Docs

License

MIT © zaflun