Skip to main content

​
Overlay Helpers

The @wormkey/overlay package provides helpers to automatically inject the Wormkey control bar without manual script tags.

​
Installation

npm install @wormkey/overlay

​
Auto-Mount (/auto)

Automatically detect and load the overlay script on page load.

​
Usage

Import at your app entry point: 
// src/main.ts or src/index.ts
import "@wormkey/overlay/auto";

​
Configuration

Add a meta tag to your HTML:
<meta
  name="wormkey-overlay-url"
  content="https://wormkey.run/.wormkey/overlay.js?slug=quiet-lime-42"
/>
The auto script reads this tag and injects the overlay.

​
How It Works

1

Detect script URL

Checks (in order):
  1. Function parameter
  2. window.__WORMKEY_OVERLAY_URL__
  3. <meta name="wormkey-overlay-url">
2

Create script element

Generates <script defer data-wormkey-overlay="1" src="..."></script>
3

Append to DOM

Injects into document.head. Skips if already present.

​
Return Value

The auto() function returns a boolean: 
import { auto } from "@wormkey/overlay";

const loaded = auto();
console.log(loaded ? "Overlay loaded" : "No URL found");

​
Express Middleware (/express)

Automatically inject the overlay script into HTML responses.

​
Usage

import express from "express";
import { wormkeyOverlayMiddleware } from "@wormkey/overlay/express";

const app = express();

app.use(
  wormkeyOverlayMiddleware({
    scriptUrl: "https://wormkey.run/.wormkey/overlay.js?slug=quiet-lime-42",
  })
);

app.get("/", (req, res) => {
  res.send(`
    <!DOCTYPE html>
    <html>
      <head><title>My App</title></head>
      <body><h1>Hello World</h1></body>
    </html>
  `);
});

app.listen(3000);

​
Options

​
scriptUrl (required)

Full overlay script URL: 
wormkeyOverlayMiddleware({
  scriptUrl: "https://wormkey.run/.wormkey/overlay.js?slug=quiet-lime-42",
});

​
How It Works

1

Intercept res.send

Wraps the Express res.send() method to inspect responses.
2

Check content type

Only modifies responses with Content-Type: text/html.
3

Inject script tag

Inserts before </head> if present, otherwise at the start of the body:
<script defer data-wormkey-overlay="1" src="..."></script>
4

Skip duplicates

Does not inject if data-wormkey-overlay="1" already exists.

​
Dynamic Script URL

Read from environment variables: 
const scriptUrl = process.env.WORMKEY_OVERLAY_URL ?? "";

if (scriptUrl) {
  app.use(wormkeyOverlayMiddleware({ scriptUrl }));
}

​
Use with Other Middleware

Place after body parsers, before routes: 
import express from "express";
import { wormkeyOverlayMiddleware } from "@wormkey/overlay/express";

const app = express();

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Add Wormkey overlay
app.use(
  wormkeyOverlayMiddleware({
    scriptUrl: "https://wormkey.run/.wormkey/overlay.js?slug=quiet-lime-42",
  })
);

// Define routes
app.get("/", (req, res) => {
  res.send("<html><body>Hello</body></html>");
});

app.listen(3000);

​
React Component (/react)

For React and Next.js apps, use the <WormkeyOverlay /> component: 
import { WormkeyOverlay } from "@wormkey/overlay/react";
// or
import { WormkeyOverlay } from "wormkey";

<WormkeyOverlay gatewayUrl="https://wormkey.run" />;
See React Integration for full details.

​
Comparison

HelperUse CaseFramework
/autoAuto-detect and injectVanilla JS, Vite, Webpack
/expressServer-side HTML injectionExpress, Node.js
/reactReact componentReact, Next.js

​
Local Development

When using wormkey http 3000 --local, update URLs: 
// Auto-mount with local gateway
import { auto } from "@wormkey/overlay";
auto("http://localhost:3002/.wormkey/overlay.js?slug=quiet-lime-42");

// Express with local gateway
app.use(
  wormkeyOverlayMiddleware({
    scriptUrl: "http://localhost:3002/.wormkey/overlay.js?slug=quiet-lime-42",
  })
);

​
Manual Script Tag

If you prefer not to use helpers, add the script tag directly: 
<script
  defer
  data-wormkey-overlay="1"
  src="https://wormkey.run/.wormkey/overlay.js?slug=quiet-lime-42"
></script>

Build docs developers (and LLMs) love

Get started for freeTalk to us