@saaspro/react

React bindings for the SaaS Pro browser SDK: an SSR-safe provider, hooks for tracking and feature flags, tracked components and an error boundary.

npm install @saaspro/react

Peer dependencies: react >= 18, and next >= 14 only if you import @saaspro/react/next.

Flag hooks use React's external-store subscription contract with stable snapshots and an empty SSR snapshot, avoiding hydration mismatches with browser storage. A provider may receive its initial key asynchronously. Once initialized, its configuration is immutable: use a new isolated client to change projects. Changing the client also resets route deduplication and flag subscriptions.

Quick start

// app/layout.tsx  (or your root component)
import { SaaSProMaxProvider } from "@saaspro/react";
import { SPMPageview } from "@saaspro/react/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SaaSProMaxProvider config={{ key: process.env.NEXT_PUBLIC_SPM_KEY! }}>
          <SPMPageview />
          {children}
        </SaaSProMaxProvider>
      </body>
    </html>
  );
}

The provider initialises the browser SDK in an effect, exactly once per client, even under StrictMode double-effects. Nothing touches window while rendering on the server. Any component that tracks on mount is safe: calls made before initialisation are buffered by the SDK and replayed.

Outside Next.js, drive pageviews from your own router:

import { SPMPageview } from "@saaspro/react";

<SPMPageview pathname={location.pathname} search={location.search} />

Hooks

const spm = useSaaSProMax();            // the client itself
const track = useTrack();               // track(name, properties?, options?)
const identify = useIdentify();         // identify(distinctId, traits?)
const page = usePage();                 // page(name?, properties?)
const report = useCaptureException();   // captureException(error, options?)
const reportWithTags = useErrorReporter(); // (error, tags?) — the common case

usePageview(pathname, search);          // a $pageview per route change

const flags = useFlags();                          // every cached flag
const variant = useFlag("checkout-copy", "control");
const on = useFeatureEnabled("new-onboarding");    // boolean
const loaded = useLoadFlags({ plan: "pro" });      // fetch once, then re-render on change

All the callbacks are stable across renders, so they are safe in dependency arrays.

Components

<TrackedButton event="cta clicked" properties={{ position: "hero" }} value={49} currency="EUR">
  Start free
</TrackedButton>

Sends the event, then calls your onClick. Every other <button> prop passes through.

<TrackOnView event="pricing seen" properties={{ section: "plans" }} threshold={0.5}>
  <PricingTable />
</TrackOnView>

Fires once when the block scrolls into view (repeat fires every time). If IntersectionObserver is unavailable it fires on mount, so the event is never silently lost. as picks the wrapper element (div by default).

<SPMErrorBoundary
  tags={{ area: "checkout" }}
  fallback={(error, reset) => <Oops error={error} onRetry={reset} />}
>
  <Checkout />
</SPMErrorBoundary>

Reports the error as unhandled with mechanism: "boundary" and the component stack, then renders the fallback. React requires error boundaries to be class components, so this one cannot read context — pass client if you are not using the shared singleton.

<FeatureFlag flag="new-onboarding" fallback={<OldFlow />}>
  <NewFlow />
</FeatureFlag>

<FeatureFlag flag="checkout-copy" variant="urgent">
  <UrgentCopy />
</FeatureFlag>

Multiple clients

SaaSProMaxProvider uses the shared singleton by default. Pass your own for tests or multi-key pages:

import { createClient } from "@saaspro/react";

const client = createClient();
<SaaSProMaxProvider client={client} config={{ key }}>…</SaaSProMaxProvider>

License

MIT

Flag values on the first render

@saaspro/react/flags-bootstrap provides FlagBootstrapProvider, useBootstrapFlag and useBootstrapFlags for a server-created, selected-value payload. Identity, complete context, consent, environment, explicit keys and expiry are checked before rendering. Browser activation also checks the current SDK state. See local flags and SSR bootstrap for private caching, browser-safe properties and lifecycle requirements.