React SDK

@whisperr/react gives a React app one Whisperr client through a provider and a hook. It wraps @whisperr/web, so every behavior on that page applies here. On the Next.js App Router, use @whisperr/next.

Install

npm i @whisperr/react @whisperr/web

The packages are @whisperr/react and @whisperr/web on npm. They release together; the current version is 0.4.0. React 17 or later is required.

Quickstart

App.tsx

import { WhisperrProvider, useWhisperr } from "@whisperr/react";

export function App() {
  return (
    <WhisperrProvider apiKey="wpk_your_publishable_key">
      <NewProject />
    </WhisperrProvider>
  );
}

function NewProject({ createProject }: { createProject: () => Promise<void> }) {
  const whisperr = useWhisperr();
  // Track after the action succeeds. "project_created" is an example name.
  async function create() {
    await createProject();
    whisperr.track("project_created", { template: "blank" });
  }
  return <button onClick={create}>New project</button>;
}

Use a publishable key (wpk_…), shown as an App key in Settings → API keys. Never put a server key (wrk_…) in React code.

How do I pass more options to WhisperrProvider?

WhisperrProvider takes either apiKey or a full options object with any Web SDK option:

App.tsx

<WhisperrProvider
  options={{
    apiKey: "wpk_your_publishable_key",
    appVersion: "2.4.0",
    onError: (error) => console.warn("whisperr", error.type, error.message),
  }}
>
  <Routes />
</WhisperrProvider>

The provider creates the client once, on first render. Changing its props later has no effect.

How do I identify the user in React?

Call identify() after sign-in and when you restore a signed-in session. Call reset() on sign-out.

useWhisperrIdentity.ts

import { useEffect } from "react";
import { useWhisperr } from "@whisperr/react";

export function useWhisperrIdentity(user: { id: string; plan: string } | null) {
  const whisperr = useWhisperr();
  useEffect(() => {
    if (user) whisperr.identify(user.id, { traits: { plan: user.plan } });
  }, [whisperr, user?.id]);
}

Events tracked before identify() go out under an anonymous id and move to the user when you identify them. See What happens before the user signs in?

How do I send the app language from React?

Call setAppLanguage() with the language the user picked in your product. Calling it with an unchanged value sends nothing.

const whisperr = useWhisperr();
useEffect(() => whisperr.setAppLanguage(i18n.language), [i18n.language]);

Server-side rendering

WhisperrProvider is safe to render on the server. Outside a browser the client captures and sends nothing.

Common questions

Is WhisperrProvider safe under React StrictMode?

Yes. The provider creates the client once, and Whisperr.init() returns the same client on every later call, so a double render does not create a second client.

What does useWhisperr() return?

The @whisperr/web client: identify(), track(), page(), setAppLanguage(), flush(), reset(), optIn() and optOut(). It throws when it is used outside a WhisperrProvider.