Skip to main content

Quickstart

Build and run your first Lumio extension in 5 minutes.

0. Apply as a developer​

Before using the CLI, you need an approved developer profile. If you have not applied yet, follow the steps in Becoming a Developer to submit your application and wait for approval. The lumio init command requires an approved developer profile to create extensions.

1. Install the CLI​

npm install -g @zaflun/lumio-cli

2. Log in to Lumio​

lumio login

This opens your browser for PKCE OAuth authentication. After login, credentials are stored in ~/.lumio/credentials.

For non-interactive environments (CI/CD), mint a developer key (lm_dev_*) under Settings → You → Developer → Developer keys (/dashboard/settings/developer/keys) and pass it to the CLI - it is scoped for publishing and works without the Pro plan (see lumio login):

lumio login --token lm_dev_your_developer_key_here

3. Scaffold a new extension​

lumio init my-first-extension

The interactive wizard asks:

? Extension name: My First Extension
? Description: A hello world extension
? Category: widget
? Targets: editor, layer
? Server functions: no

This creates the extension on Lumio (generating an Extension-ID), scaffolds the project, and writes lumio.config.json.

4. Set up AI assistant (optional)​

If you use an AI coding assistant (Claude Code, Copilot, Cursor, Gemini, Windsurf, Codex), install the Lumio skill files so your assistant understands the SDK:

npx @zaflun/lumio-agent-skill add

This creates .lumio/skills/ with reference docs that teach your assistant about components, hooks, server functions, and CLI commands. See AI Assistant Integration for per-tool setup.

5. Start the dev server​

cd my-first-extension
pnpm install
lumio dev

This starts the esbuild watcher and local mock-host sandbox at http://127.0.0.1:3100/. The URL is printed in the terminal; open it in your browser, or use lumio dev --open. The editor and layer share the same local storage and event session.

In another terminal, send an event to that session:

lumio trigger twitch:follower --user Alice

The lumio dev and lumio trigger pages show the sandbox panels, presets, and repeated event loads. Local development uses the @zaflun/lumio-devkit mock host and needs no stream or staging API connection.

6. Edit the extension​

Open src/editor.tsx:

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

function Settings() {
  const [visible, setVisible] = useExtensionStorage("visible", false);
  const [text, setText] = useExtensionStorage("text", "");
  return (
    <CompactView title="My First Extension">
      <Toggle label="Visible" checked={visible} onChange={setVisible} />
      <TextField label="Message" value={text} onChange={setText} />
    </CompactView>
  );
}

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

Open src/layer.tsx:

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

function Overlay() {
  const [visible] = useExtensionStorage("visible", false);
  const [text] = useExtensionStorage("text", "");
  if (!visible) return null;
  return <Text content={text || "Hello World"} variant="heading" />;
}

Lumio.render(<Overlay />, { target: "layer" });

Changes in the editor surface propagate to the layer in real time.

7. Build and deploy​

lumio build
lumio deploy -v 1.0.0 -d "Initial release"

Your extension is now uploaded as a draft. Use the submission wizard in the dashboard to submit it for review.

AI-Assisted Development

Building with an AI coding assistant? Feed it the full Lumio documentation in one go:

  • llms.txt - structured index of all documentation pages
  • llms-full.txt - complete documentation in a single file

Paste the URL or content into your assistant's context for accurate Lumio extension help. For deeper integration, install the @zaflun/lumio-agent-skill package.

Next steps​