Overlay authoring

Overlays are local web projects served by Stream Kit. Author overlays by editing the project files and overlay.manifest.json in the overlay folder.

Manifest

Each overlay includes overlay.manifest.json:

{
  "id": "my-alert-overlay",
  "name": "My Alerts",
  "framework": "svelte",
  "expectedEvents": ["alert", "clear"],
  "outgoingEvents": ["button:clicked", "alert:dismissed"],
  "settings": [],
  "testHandlers": [],
  "requiredPlugins": ["twitch"],
  "actions": []
}

Field	Description
`id`	Stable overlay id (folder name)
`name`	Display name in the app
`framework`	Starter template id (`vanilla`, `svelte`, `react`, …)
`expectedEvents`	Event names for Send to Overlay combobox (app → overlay)
`outgoingEvents`	Event names this overlay sends to Stream Kit (overlay → app); used for Message Received trigger setup
`settings`	Configure page fields (text, switch, select, slider, color, sections)
`testHandlers`	Quick test buttons on overlay detail page
`requiredPlugins`	Plugin keys required for action presets
`actions`	Optional action presets to install

Settings

Settings fields render on the overlay Configure page. Values are broadcast to the browser source as event overlay:settings with a key-value map.

Supported field types: text, switch, checkbox, select, slider, color, and grouped section blocks.

Use __overlay__ token in select items when a field should reference the current overlay id.

Receiving events

The overlay runtime connects to ws://127.0.0.1:PORT/ws?overlayId=.... Incoming messages use this shape:

{ "event": "alert", "payload": { "username": "viewer" } }

The reserved event overlay:settings is only sent from Stream Kit to the overlay.

Sending events to Stream Kit

Use the starter's connectOverlay() helper, which returns a send() function:

const overlay = connectOverlay({
  'overlay:settings': (payload) => applySettings(payload),
  alert: (payload) => showAlert(payload)
});

document.getElementById('follow-btn')?.addEventListener('click', () => {
  overlay.send('button:clicked', { id: 'follow' });
});

Stream Kit receives these messages and can run actions via Overlay → Message Received (overlay:overlay:message-received).

Listen for inbound messages manually:

socket.addEventListener('message', (event) => {
  const { event: eventName, payload } = JSON.parse(event.data);
  if (eventName === 'alert') {
    showAlert(payload);
  }
});

Payload from actions

Send to Overlay payload supports two modes:

Mode	Use when
JSON	Build a payload template with `\{variables\}`. Quoted standalone placeholders are cast to real JSON when the value is valid JSON (objects, arrays, numbers, booleans, or `null`). For example, `"\{message\}"` sends the object when `{message}` is a JSON object.
Variable	Pass one variable through unchanged — for example `{message}` when the trigger already provides a JSON object.

Leave payload empty to receive the full trigger context.

Handler ID: overlay:overlay:send-to-overlay.

Action presets

Presets bundle triggers and handlers users can install from the overlay page:

{
  "key": "follow-alert",
  "name": "Follow alert",
  "enabled": true,
  "triggers": [
    {
      "triggerTypeId": "twitch:twitch:channel:new-follower",
      "conditions": {}
    }
  ],
  "handlers": [
    {
      "handlerTypeId": "overlay:overlay:send-to-overlay",
      "fields": [
        { "key": "overlay", "value": "__overlay__" },
        { "key": "event", "value": "alert" },
        { "key": "payload", "value": "{\"username\":\"{username}\"}" }
      ]
    }
  ]
}

handlerTypeId and triggerTypeId must match API Reference IDs.

Editing code

From the overlay card, open the project folder in your editor or use the built-in open-folder action. Rebuild if your framework requires a build step (starters include dev scripts).

Overlay authoring

On this page