Skip to main content

​
React Integration

The <WormkeyOverlay /> component automatically loads the Wormkey control bar in your React or Next.js application when viewed through a wormhole URL.

​
Installation

npm install wormkey

​
Quick Start

​
Next.js App Router

Add the component to your root layout: 
// app/layout.tsx
import { WormkeyOverlay } from "wormkey";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <WormkeyOverlay
          gatewayUrl={process.env.NEXT_PUBLIC_WORMKEY_GATEWAY_URL ?? "https://wormkey.run"}
        />
      </body>
    </html>
  );
}

​
Next.js Pages Router

Add to _app.tsx: 
// pages/_app.tsx
import { WormkeyOverlay } from "wormkey";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <WormkeyOverlay gatewayUrl="https://wormkey.run" />
    </>
  );
}

​
React (Vite, CRA)

Add to your root component: 
// src/App.tsx
import { WormkeyOverlay } from "wormkey";

export default function App() {
  return (
    <div>
      {/* Your app content */}
      <WormkeyOverlay gatewayUrl="https://wormkey.run" />
    </div>
  );
}

​
Props

The WormkeyOverlay component accepts the following props:

​
scriptUrl

Full overlay script URL from the CLI output. 
<WormkeyOverlay
  scriptUrl="https://wormkey.run/.wormkey/overlay.js?slug=pale-snow-91"
/>
Type: string (optional)

​
gatewayUrl

Gateway base URL. Use with automatic slug detection. 
<WormkeyOverlay gatewayUrl="https://wormkey.run" />
Type: string (optional)
Default: process.env.NEXT_PUBLIC_WORMKEY_GATEWAY_URL

​
slug

Explicit wormhole slug. Auto-detected from /s/:slug URLs if omitted. 
<WormkeyOverlay
  gatewayUrl="https://wormkey.run"
  slug="quiet-lime-42"
/>
Type: string (optional)

​
Configuration Approaches

Set NEXT_PUBLIC_WORMKEY_GATEWAY_URL in .env.local:
# .env.local
NEXT_PUBLIC_WORMKEY_GATEWAY_URL=https://wormkey.run
Use in your layout:
<WormkeyOverlay
  gatewayUrl={process.env.NEXT_PUBLIC_WORMKEY_GATEWAY_URL}
/>
The component automatically detects the slug from the URL.

​
How It Works

1

Detect configuration

The component checks for scriptUrl, or derives it from gatewayUrl + slug.
2

Auto-detect slug

If no slug prop is provided, it reads from window.location.pathname matching /s/:slug.
3

Load overlay script

Injects <script defer src="..." data-wormkey-overlay="1"> into the DOM.
4

Render control bar

The overlay script renders the control bar when accessed through a wormhole URL.

​
Local Development

For local testing with wormkey http 3000 --local: 
<WormkeyOverlay
  gatewayUrl={process.env.NEXT_PUBLIC_WORMKEY_GATEWAY_URL ?? "http://localhost:3002"}
/>

​
Server-Side Rendering

The component is marked "use client" and safe for SSR frameworks. It only runs in the browser: 
// app/layout.tsx (Next.js 13+)
import { WormkeyOverlay } from "wormkey";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <WormkeyOverlay gatewayUrl="https://wormkey.run" />
      </body>
    </html>
  );
}
No additional client/server boundary needed.

​
TypeScript

Full TypeScript support included: 
import { WormkeyOverlay, type WormkeyOverlayProps } from "wormkey";

const overlayProps: WormkeyOverlayProps = {
  gatewayUrl: "https://wormkey.run",
  slug: "quiet-lime-42",
};

<WormkeyOverlay {...overlayProps} />;

Build docs developers (and LLMs) love

Get started for freeTalk to us