Next.js Client SDK

Source code: statsig-io/js-client-monorepo

Set Up the SDK

AI-powered Setup

Setup Statsig in 90 seconds by copying this AI prompt into your IDE:

Prompt

# Statsig SDK Integration for Next.js

You are a frontend engineer integrating the Statsig SDK into a **Next.js application**. Follow all steps below one by one:

---

## Full Integration Instructions

1. **Detect the package manager** by checking for:
   - `package-lock.json` → use `npm`
   - `yarn.lock` → use `yarn`
   - `pnpm-lock.yaml` → use `pnpm`

2. **Detect the Next.js router type** by checking for:
   - `app/` directory → **App Router**
   - `pages/` directory → **Pages Router**

3. **Install the Statsig package** using the correct package manager:

# For npm
npm install @statsig/react-bindings @statsig/session-replay @statsig/web-analytics

# For yarn
yarn add @statsig/react-bindings @statsig/session-replay @statsig/web-analytics

# For pnpm
pnpm add @statsig/react-bindings @statsig/session-replay @statsig/web-analytics

4. Add your Statsig client key to .env.local:

NEXT_PUBLIC_STATSIG_CLIENT_KEY=ask the user for their CLIENT KEY and use that input

5. Integrate Statsig into the app (auto-detect router type):

### If the project uses the App Router (has an app/ directory):

// Create app/my-statsig.tsx
"use client";

import React from "react";
import { LogLevel, StatsigProvider } from "@statsig/react-bindings";

export default function MyStatsig({ children }: { children: React.ReactNode }) {
  const id = typeof userID !== "undefined" ? userID : "a-user";

  const user = {
    userID: id,
    // Optional additional fields:
    // email: 'user@example.com',
    // customIDs: { internalID: 'internal-123' },
    // custom: { plan: 'premium' }
  };

  return (
    <StatsigProvider
      sdkKey={process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY!}
      user={user}
      options={{ logLevel: LogLevel.Debug }}
    >
      {children}
    </StatsigProvider>
  );
}

// Update app/layout.tsx to wrap children with MyStatsig
import MyStatsig from "./my-statsig";

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en">
      <body>
        <MyStatsig>
          {children} {/* Preserve all existing layout content */}
        </MyStatsig>
      </body>
    </html>
  );
}

### If the project uses the Pages Router (has a pages/ directory):

// Update pages/_app.tsx
import type { AppProps } from "next/app";
import { LogLevel, StatsigProvider } from "@statsig/react-bindings";

export default function App({ Component, pageProps }: AppProps) {
  const id = typeof userID !== "undefined" ? userID : "a-user";

  const user = {
    userID: id,
    // Optional additional fields:
    // email: 'user@example.com',
    // customIDs: { internalID: 'internal-123' },
    // custom: { plan: 'premium' }
  };

  return (
    <StatsigProvider
      sdkKey={process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY!}
      user={user}
      options={{ logLevel: LogLevel.Debug }}
    >
      <Component {...pageProps} /> {/* Preserve all existing pages */}
    </StatsigProvider>
  );
}

### Final Notes

- The system must **detect the router type** and **apply the correct integration automatically**.
- **Do not remove or change any existing JSX or layout structure** — only wrap the app with `StatsigProvider`.
- **Preserve the file's language**: if it's TypeScript (`.tsx`), keep it as TypeScript; if it's JavaScript (`.jsx`), keep it as JavaScript.
- After these steps, Statsig will be integrated across the entire app, with **feature gates, configs, and experiments** available everywhere.

Manual Setup

Statsig supports both Page Router & App Router, with some differences in integration patterns.

App Router
Page Router

Set environment variables

Add the keys to your .env.local file:

.env.local

# the NEXT_PUBLIC_ prefix is required for this to be available on the client side
NEXT_PUBLIC_STATSIG_CLIENT_KEY=client-<REPLACE_WITH_YOUR_CLIENT_KEY>
STATSIG_SERVER_KEY=secret-<REPLACE_WITH_YOUR_SERVER_KEY>

Install packages

For App Router, install the @statsig/next package:

npm i @statsig/next

yarn add @statsig/next

pnpm add @statsig/next

Add the StatsigBootstrapProvider

The <StatsigBootstrapProvider> creates both a Statsig Client and Server instance under the hood, and “bootstraps” the client so it can render each page without a blocking network request. this will keep your app speedy and is recommended for most users. If you need more control over your setup, our Bootstrapping and React docs can provide more guidance.Add this component around the content in your root layout.tsx file:

app/layout.tsx

import { StatsigBootstrapProvider } from "@statsig/next"

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {

  const user = {
    userID: "user-123", // add additional parameters as needed
  };
  return (
    <html lang="en">
      <body>
        <StatsigBootstrapProvider
          user={user}
          clientKey={process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY}
          serverKey={process.env.STATSIG_SERVER_KEY}
        >
          {children}
        </StatsigBootstrapProvider>
      </body>
    </html>
  );
}

Set environment variables

Add the keys to your .env.local file:

.env.local

# the NEXT_PUBLIC_ prefix is required for this to be available on the client side
NEXT_PUBLIC_STATSIG_CLIENT_KEY=client-<REPLACE_WITH_YOUR_CLIENT_KEY>

Install packages

Install the @statsig/react-bindings package:

npm i @statsig/react-bindings @statsig/web-analytics

yarn add @statsig/react-bindings @statsig/web-analytics

pnpm add @statsig/react-bindings @statsig/web-analytics

Add StatsigProvider to _app.tsx

To integrate Statsig into your Page Router app you can add the StatsigProvider to your _app.tsx file.There is a full example in the samples directory of the javascript sdk.

pages/_app.tsx

import type { AppProps } from "next/app";

import {
  LogLevel,
  StatsigProvider,
} from "@statsig/react-bindings";
import { StatsigAutoCapturePlugin } from '@statsig/web-analytics';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <StatsigProvider
      sdkKey={process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY!}
      user={{ userID: "a-user" }}
      options={{
        plugins: [ new StatsigAutoCapturePlugin() ],
      }}>
      <Component {...pageProps} />
    </StatsigProvider>
  );
}

See the User (StatsigUser) doc for more info on the user property. From here, you’re ready to start checking gates & experiments and sending events in any sub-file of layout.tsx!

Use the SDK

Checking a Feature Flag/Gate

Now that your SDK is initialized, let’s check a Feature Gate. Feature Gates can be used to create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always CLOSED or OFF (think return false;) by default.

App Router
Page Router

'use client';

import { useGateValue } from "@statsig/react-bindings";

export default function Home() {
  const gate = useGateValue("my_gate");

  return (
    <div>
      Gate Value: {gate ? 'PASSED' : 'FAILED'}
    </div>
  );
}