Install StageWhisper in React

StageWhisper installs in a React app with the same one-line script tag as everywhere else — no npm package, no provider component, nothing to render. Add the tag to your HTML shell (or inject it once from useEffect) and the widget mounts itself alongside your app.

Prerequisites

A StageWhisper site created in the dashboard.
Your app’s origin on the site’s origin allowlist — enable the localhost toggle if you’re testing locally.

Add the loader to index.html

Vite-based React projects keep an editable index.html at the project root — the shell page that boots your app. That makes the recommended install a single paste, with no React code involved.

Open index.html at the root of your project.
Paste the one-liner before the closing </head> tag, and swap pub_your_site_key for the public site key shown on your site’s install page in the dashboard.
Reload the page — Vite serves index.html directly, so there’s nothing to rebuild.

index.html

<!-- index.html -->
<head>
  <meta charset="UTF-8" />
  <title>My React App</title>
  <script async src="https://cdn.stagewhisper.co/loader.js" data-sw-key="pub_your_site_key"></script>
</head>

<!-- index.html -->
<head>
  <meta charset="UTF-8" />
  <title>My React App</title>
  <script async src="https://cdn.stagewhisper.co/loader.js" data-sw-key="pub_your_site_key"></script>
</head>

Running a strict Content Security Policy? The Content Security Policy guide covers the exact directives and where the nonce goes.

No HTML shell? Inject it from useEffect

Some setups don’t expose an editable HTML shell. In that case, inject the loader from a top-level useEffect instead. Run it once at the app root — your App component or equivalent — never per-page or per-component. The guard on the first line keeps the tag single even when React StrictMode double-invokes effects in development.

App component

import { useEffect } from "react";

export default function App() {
  useEffect(() => {
    if (document.querySelector('script[data-sw-key]')) return;

    const script = document.createElement("script");
    script.async = true;
    script.src = "https://cdn.stagewhisper.co/loader.js";
    script.setAttribute("data-sw-key", "pub_your_site_key");
    document.head.appendChild(script);
  }, []);

  return <YourAppRoutes />;
}

import { useEffect } from "react";

export default function App() {
  useEffect(() => {
    if (document.querySelector('script[data-sw-key]')) return;

    const script = document.createElement("script");
    script.async = true;
    script.src = "https://cdn.stagewhisper.co/loader.js";
    script.setAttribute("data-sw-key", "pub_your_site_key");
    document.head.appendChild(script);
  }, []);

  return <YourAppRoutes />;
}

React Router

Client-side navigation is handled automatically — the widget re-evaluates your URL rules whenever React Router updates history state, so route changes need no extra wiring. Install the loader once at the shell or app root and let it follow your routes from there.

Verify

Refresh your app, then watch the site’s install status in the dashboard — it flips the moment the first ping arrives.

Widget not showing up? Head to Troubleshooting for the usual suspects — blocked origins, CSP, localhost, and stale config.