React

Updated 2026-11-02

Setup

Headstream doesn't need an npm package. Copy your snippet from Project settings and paste it into the <head> of index.html.

<head>
  <script
    defer
    src="https://headstream-ingest.super-dream-7005.workers.dev/t.js"
    data-key="YOUR_KEY"
  ></script>
</head>

This works with Vite and other setups that ship an index.html. Using Next.js? See the Next.js setup.

Single-page routing

The script watches history.pushState, history.replaceState and the popstate event. Client-side routers built on the history API, such as React Router, need no extra code. Each route change is a pageview.

Track events and identify people

The script adds a headstream global. It's loaded after your HTML parses, so use optional chaining:

function PricingButton() {
  return (
    <button onClick={() => window.headstream?.track("pricing_click", { plan: "growth" })}>
      Choose Growth
    </button>
  );
}

After sign-in, link the browser to the person:

window.headstream?.identify({ email: user.email });

For TypeScript, add a type for the global:

declare global {
  interface Window {
    headstream?: {
      track: (name: string, properties?: Record<string, unknown>) => void;
      identify: (traits: Record<string, unknown>) => void;
    };
  }
}
export {};

Check it works

Deploy and load a page on a domain listed in your project. Events from localhost are rejected. A Content Security Policy must allow the ingest host in script-src and connect-src.

More detail is in track events and identify people.