@offstage/react

React bindings for the Offstage browser SDK. Works with React 19, Server Components, and TanStack Start / Next.js / Remix out of the box.

Install

pnpm add @offstage/react react

@offstage/browser is bundled as a regular dependency — you don't need to install it explicitly.

Quick start

Wrap your app once at the root:

import { OffstageProvider } from "@offstage/react";

export function App({ children }: { children: React.ReactNode }) {
  return <OffstageProvider apiKey="pk_live_...">{children}</OffstageProvider>;
}

Then track from any client component:

"use client";

import { useOffstage } from "@offstage/react";

export function SignupButton() {
  const { track, identify } = useOffstage();

  return (
    <button
      onClick={() => {
        identify("user_123", { plan: "pro" });
        track("signup_completed");
      }}
    >
      Sign up
    </button>
  );
}

API

<OffstageProvider />

| Prop | Type | Default | Description | | --------------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | string | — | Your Offstage publishable API key. | | host | string | — | Override the ingest host (self-hosted deployments). | | autoPageviews | boolean | true | Emit a pageview on initial mount and on history navigation. | | consent | boolean | true | Pass false to no-op until you re-render the provider with true. | | enabled | boolean | auto | Hard kill switch. When omitted, auto-disables on localhost / 127.0.0.1 so dev traffic doesn't pollute production. Pass true to force-on or false to force-off. | | children | ReactNode | — | Your tree. |

The provider is SSR-safe: it doesn't instantiate the SDK during server rendering.

useOffstage()

Returns { track, identify, pageview } bound to the active provider. Throws if called outside <OffstageProvider> — that's a wiring bug, not a tracking error, so it surfaces loudly.

const { track, identify, pageview } = useOffstage();

track("event_name", { foo: "bar" });
identify("user_id", { email: "..." });
pageview("/custom-path"); // optional, defaults to current path

See @offstage/browser for the underlying tracking semantics, payload shape, and storage model.