Home / Docs

Build and test overlays locally

The overlaify command lets you work on an overlay as a plain HTML file on your own machine: preview it with fake subs and raids, run it in OBS with live reload, check it against the spec, and publish it when it's ready. It's free and open source.

Install

You need Node.js 18 or newer. Nothing else: run it with npx, which fetches the latest version each time.

npx overlaify --help

Or install it once and drop the npx:

npm install -g overlaify
overlaify --help

The examples below use npx overlaify. The source is on GitHub.

Start an overlay

An overlay is one HTML file. Make a blank starter, or start from any overlay in the Library:

npx overlaify init my-alert.html                    # blank starter
npx overlaify init --list                           # list the library templates
npx overlaify init goal.html --template goal-bar    # copy a template

init won't overwrite an existing file unless you add --force.

Preview with overlaify dev

This is where you'll spend most of your time. Point it at your file:

npx overlaify dev my-alert.html
overlaify dev my-alert.html

  Dev page   http://127.0.0.1:4545/
  OBS URL    http://127.0.0.1:4545/overlay  (Browser source, 1920 × 1080)

Saving the file reloads the preview and OBS. Ctrl+C to stop.

If there's only one .html file in the folder you can leave out the name. Open the dev page in your browser. It has:

Edit and save, and it reloads. The preview and every copy open in OBS reload as soon as the file changes, in any editor. You never need to restart the command.

Options:

OptionWhat it does
--port 4545The port to use. If it's taken, the next free one is used.
--channel yournameYour Twitch channel, so the overlay gets real chat and events. Saved, so you only pass it once.
--host 0.0.0.0Listen on your network, not only this computer. Use it to reach the overlay from a second streaming PC.

Test it in OBS

The simulated events tell you how it looks. OBS tells you how it looks on stream. Add the local URL as a source:

  1. In OBS, add a Browser source and set the URL to http://127.0.0.1:4545/overlay.
  2. Set the size to 1920 × 1080.
  3. Set your channel with --channel or in the dev page's properties. The overlay now gets real chat and events from your Twitch channel, anonymously.

The dev page shows whether OBS is connected. Action keys you press on the dev page reach every running copy, OBS included, and the dev page tells you if a copy has no handler for one. The event buttons only fire in the preview; to see something in OBS, type in your own chat. Each save reloads the OBS source too, so keep OBS open while you work.

Two-PC setup? Start it with --host 0.0.0.0 and use this computer's network address in the streaming PC's OBS, for example http://192.168.1.20:4545/overlay. Your firewall may ask you to allow Node.

The local URL only works while overlaify dev is running. For a URL that's always there, publish the overlay.

Properties and action keys

An overlay declares what can be changed in a JSON manifest inside the file. Properties are values the streamer picks once (a color, a goal, a sound on or off). Actions are buttons pressed during the stream (pause the timer, add a death, reset):

<script type="application/json" id="overlaify-manifest">
{ "spec": 1,
  "properties": [{ "key": "color", "label": "Color", "type": "color", "default": "#c6ff3d" }],
  "actions":  [{ "name": "reset", "label": "Reset", "style": "danger", "confirm": true }] }
</script>

The overlay reads them with Overlaify.param('color') and Overlaify.action('reset', fn). The dev page builds its properties panel and action keys from this manifest, so add a property, save, and its control appears.

The values you pick are saved next to your file, in .overlaify/my-alert.json. They're used every time you run dev, and they come along when you publish. Changing a property reloads the overlay everywhere, OBS included.

Check it against the spec

The dev page checks as you go. To check from the terminal or in CI:

npx overlaify validate my-alert.html          # exit code 1 on errors
npx overlaify validate overlays/*.html --json # machine-readable

The main rules: one self-contained HTML file, at most 80 KB, a transparent 1920 × 1080 canvas, and the only script it loads is the Overlaify SDK. Print the full spec any time with:

npx overlaify spec

It's also in the repo as overlay-spec.md.

Publish to overlaify.com

When it works locally, put it online. That gives you an OBS URL that doesn't depend on your computer, a page at overlaify.com/<you>/<name>, and the live control page for its action keys.

npx overlaify login                           # opens the browser: sign in, click Allow
npx overlaify publish my-alert.html           # first time: choose private or public
npx overlaify publish my-alert.html           # again: a new version of the same overlay

The first publish names the overlay after the file (my-alert.html → my-alert). Useful options:

OptionWhat it does
--public / --privateSkip the question.
--name neonIts address: overlaify.com/<you>/neon.
--title "Neon Alerts"The title shown in My overlays.
--kind alertalert, chat, goal, ticker, frame or custom.
--newPublish as a separate overlay instead of a new version.

The overlay must pass the spec to publish. Which overlay a file belongs to is kept in .overlaify/my-alert.publish.json. overlaify whoami shows the connected account and overlaify logout forgets it. In CI, set OVERLAIFY_TOKEN instead of logging in.

Download an overlay to edit

Any public overlay, or your own private one, can be pulled down as a local file:

npx overlaify download alice/neon-alert                # → neon-alert.html
npx overlaify download alice/neon-alert my.html        # pick the file name
npx overlaify download alice/neon-alert --version 1    # an older version

The file runs on its own, ready for overlaify dev. For your own overlay, its saved properties come along and the file stays linked to it, so overlaify publish adds your changes as a new version.

Let Claude write it

If you use Claude Code, install the Overlaify skill once:

npx overlaify skill

It goes in ~/.claude/skills/overlaify. Then ask Claude for an overlay ("a cozy sub alert with a sleepy cat") and it writes it to the spec, validates it and opens it with overlaify dev, so you can test and ask for changes right away.

Command reference

CommandWhat it does
init [file] [--template slug] [--force]Start an overlay from the blank starter or a Library template. --list lists templates.
dev [file] [--port] [--channel] [--host]Dev page with simulated events, properties and action keys, plus an OBS URL that reloads on save.
validate <files…> [--json]Check overlays against the spec. Exit code 1 on errors.
login [--no-browser] [--token t]Connect the CLI to your overlaify.com account.
publish [file] [options]Publish to overlaify.com/<you>/<name>; again adds a version.
download <user>/<name> [file]Save an overlay from overlaify.com as a local file.
whoami / logoutShow or forget the connected account.
specPrint the Overlay Spec as Markdown.
skill [--dir path]Install the Overlaify skill for Claude.

Troubleshooting

OBS shows nothing

No real chat or events

Saving doesn't reload

Can't reach it from the second PC

Publish says it fails the spec

Rather not touch a terminal?

Describe your overlay in the studio, test it with fake events and copy one URL into OBS.

Create an overlay