Skip to main content
← All platforms
Quickstart

React

Hooks and components on top of the browser SDK. Works with the Next.js App Router and any React 18+ app.

Package
@sheepit-ai/react
Runs on
React 18+

Get an API key

Don't have an account yet? Create one, free. Then open Settings → API Keys in the dashboard and copy the publishable key (lp_pub_…). It is safe to ship inside a browser or app bundle.

Install

bash
npm install @sheepit-ai/react @sheepit-ai/sdk-js

Add the provider

app/providers.tsx
"use client";

import type { ReactNode } from "react";
import { SheepitProvider } from "@sheepit-ai/react";

export function Providers({
  children,
  user,
}: {
  children: ReactNode;
  user: { id: string; email: string } | null;
}) {
  return (
    <SheepitProvider
      config={{
        apiKey: process.env.NEXT_PUBLIC_SHEEPIT_KEY!, // lp_pub_...
      }}
      // Signed in → identify; null → reset on logout.
      user={user ? { id: user.id, traits: { email: user.email } } : null}
    >
      {children}
    </SheepitProvider>
  );
}

Wrap your app

Render Providers once, in your root layout, so every component below it can use the hooks.

app/layout.tsx
import type { ReactNode } from "react";
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {/* Pass your signed-in user here, or null when signed out. */}
        <Providers user={null}>{children}</Providers>
      </body>
    </html>
  );
}

Track events and read flags with hooks

tsx
import { useExperiment, useFlag, useTrack } from "@sheepit-ai/react";

export function Checkout() {
  const track = useTrack();
  const newCheckout = useFlag("new_checkout", false) === true;
  const { variant } = useExperiment("pricing_page");

  return (
    <button onClick={() => track("checkout_started", { variant })}>
      {newCheckout ? "Pay now" : "Checkout"}
    </button>
  );
}

Check that it worked

Click the button, then open Events in the dashboard. The checkout_started event shows up within about a minute.

Worth knowing

  • @sheepit-ai/sdk-js is a peer dependency, so install both packages.
  • If the config is invalid (for example, the key's environment variable is missing), the provider falls back to a no-op client instead of throwing. If nothing arrives, check useSheepit().status().initialized.
  • useFlag() and useExperiment() return the default you pass until the first config fetch lands.
  • Self-hosted install? Add apiUrl: "https://<your-install>/api" to the config. The docs inside your install's dashboard show the exact value.
React quickstart | Sheepit