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:
- A preview of the overlay at 1920 × 1080.
- Event buttons that fire a follow, sub, gift subs, bits, a raid or a chat message. Tick Random test events to throw a steady stream of them at it, the same as
?test=1on a hosted overlay. - A properties panel built from the overlay's manifest, plus your Twitch channel.
- The overlay's action keys (pause, add, reset…), if it declares any.
- The spec check: errors and warnings, updated every time you save.
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:
| Option | What it does |
|---|---|
--port 4545 | The port to use. If it's taken, the next free one is used. |
--channel yourname | Your Twitch channel, so the overlay gets real chat and events. Saved, so you only pass it once. |
--host 0.0.0.0 | Listen 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:
- In OBS, add a Browser source and set the URL to
http://127.0.0.1:4545/overlay. - Set the size to
1920×1080. - Set your channel with
--channelor 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
- Private overlays only open on overlaify.com for you. Their OBS URL still works.
- Public overlays can be opened and remixed by anyone with the link, and can be picked for the Library.
The first publish names the overlay after the file (my-alert.html → my-alert). Useful options:
| Option | What it does |
|---|---|
--public / --private | Skip the question. |
--name neon | Its address: overlaify.com/<you>/neon. |
--title "Neon Alerts" | The title shown in My overlays. |
--kind alert | alert, chat, goal, ticker, frame or custom. |
--new | Publish 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
| Command | What 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 / logout | Show or forget the connected account. |
spec | Print the Overlay Spec as Markdown. |
skill [--dir path] | Install the Overlaify skill for Claude. |
Troubleshooting
OBS shows nothing
- Is
overlaify devstill running? The local URL stops when you press Ctrl+C or close the terminal. - Check the port. If 4545 was taken, the command printed a different one.
- Many overlays are empty until something happens. Fire an event from the dev page.
- Right-click the source in OBS → Interact, or open the OBS URL in a browser and look at the console for errors.
No real chat or events
- Set your channel:
--channel yournameor the field in the dev page. It's your Twitch login name, not your display name. - Subs, bits and raids only arrive when they really happen on your channel. Use the event buttons to test.
Saving doesn't reload
- Make sure you're editing the file you passed to
dev, not a copy. - Make sure the OBS source points at the
/overlayURL thisdevprinted, not a hosted/o/…URL.
Can't reach it from the second PC
- Start with
--host 0.0.0.0, and use the streaming PC's view of this computer's address, not127.0.0.1. - Allow Node through this computer's firewall.
Publish says it fails the spec
- Run
npx overlaify validate my-alert.html: each error says what to fix. The usual ones are the file being over 80 KB or loading a script other than the SDK.
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