Getting Started

Quick Start

Integrate Sheepit into a React application in under five minutes. You will track your first event, gate a feature with a flag, and run your first experiment.

Get your API keys

Every project has two key types. You need both to follow this guide.

Publishable key (lp_pub_*) — used in client-side code. Store it as NEXT_PUBLIC_GT_KEY in your .env.local file.
Secret key (lp_sec_*) — used in server-side code only. Never expose this to the browser.

Go to Settings → API Keys to generate both keys for your project.

Install the SDK

Install @sheepit-ai/react. This package bundles @sheepit-ai/sdk-js automatically — you do not need to install the core package separately.

Terminal

pnpm add @sheepit-ai/react

Add the Provider

Wrap your application with GoaTechProvider. In a Next.js App Router project, create a client component and mount it in your root layout.

Pass the currently authenticated user to the user prop so that flags and experiments can be personalised. Pass null for anonymous visitors — the SDK handles both cases automatically.

app/providers.tsx

// app/providers.tsx
"use client";

import { GoaTechProvider } from "@sheepit-ai/react";
import { useAuth } from "@/hooks/use-auth";

export function Providers({ children }: { children: React.ReactNode }) {
  const { user } = useAuth();

  return (
    <GoaTechProvider
      config={{
        apiKey: process.env.NEXT_PUBLIC_GT_KEY!,
        environment:
          process.env.NODE_ENV === "production" ? "production" : "development",
      }}
      user={user ? { id: user.id, traits: { email: user.email } } : null}
    >
      {children}
    </GoaTechProvider>
  );
}

Track an event

Use the useTrack hook to fire a custom event from any client component. The first argument is the event name; the second is an optional object of properties.

Events are batched automatically and flushed to the Sheepit ingestion pipeline in the background.

SignupButton.tsx

import { useTrack } from "@sheepit-ai/react";

function SignupButton() {
  const track = useTrack();

  return (
    <button
      onClick={() => {
        track("signup_clicked", { source: "hero" });
      }}
    >
      Sign Up
    </button>
  );
}

Use a feature flag

The useFlag hook returns the current value of a flag for the identified user. The second argument is the fallback value returned while the SDK initialises or when the flag does not exist.

PricingPage.tsx

import { useFlag } from "@sheepit-ai/react";

function PricingPage() {
  const showNewPricing = useFlag("new_pricing", false);

  return showNewPricing ? <NewPricing /> : <OldPricing />;
}

You can also use the declarative Feature component when you want to conditionally render a subtree without writing an if statement:

App.tsx

import { Feature } from "@sheepit-ai/react";

function App() {
  return (
    <Feature flagKey="beta_banner" fallback={null}>
      <BetaBanner />
    </Feature>
  );
}

Run an experiment

The useExperiment hook returns the variant assigned to the current user for a named experiment. Render different UI based on the variant string.

Variant assignment is deterministic per user — the same user always receives the same variant. Results are recorded automatically whenever the hook renders.

CheckoutPage.tsx

import { useExperiment } from "@sheepit-ai/react";

function CheckoutPage() {
  const { variant } = useExperiment("checkout_flow");

  if (variant === "streamlined") {
    return <StreamlinedCheckout />;
  }
  return <StandardCheckout />;
}

Next Steps

React SDK

Full API reference for all hooks and components.

Server SDK

Flag evaluation and event tracking in Node.js and RSC.

Events

Custom events, page views, and batching.

Experiments

Run A/B tests and analyse results.