Next.js Client SDK

Statsig's SDK for Experimentation and Feature Flags in Next.js applications.

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:

text

# 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.

Set environment variables

Add the keys to your .env.local file:

bash

# 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

Add the StatsigBootstrapProvider

The <StatsigBootstrapProvider> creates both a Statsig Client and Server instance internally, and "bootstraps" the client so it can render each page without a blocking network request. This keeps your app fast and is recommended for most users. If you need more control over your setup, refer to Bootstrapping and React for more guidance.

Add this component around the content in your root layout.tsx file:

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>
  );
}

Refer to the User (StatsigUser) documentation for more information on the user property. After completing setup, you can check gates, experiments, and log 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.

tsx

'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>
  );
}

In an App Router app, you need to use the use client directive to ensure your logic runs on the frontend.

Reading a Dynamic Config

Feature Gates are useful for simple on/off switches with optional advanced user targeting. To send a different set of values (strings, numbers, etc.) to clients based on specific user attributes such as country, use Dynamic Configs. The API is similar to Feature Gates, but you get a complete JSON object you can configure on the server and fetch typed parameters from it. For example:

tsx

'use client';

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

export default function Home() {
  const config = useDynamicConfig("my_dynamic_config");

  return (
    <div>
      Title: {config.get('title', 'Fallback Title')}
    </div>
  );
}

In an App Router app, you need to use the use client directive to ensure your logic runs on the frontend.

Getting a Layer/Experiment

Layers/Experiments let you run A/B/n experiments. Two APIs are available, but Statsig recommends layers for quicker iterations with parameter reuse.

tsx

'use client';

import { useExperiment, useLayer} from "@statsig/react-bindings";

export default function Home() {
  const layer = useLayer("my_experiment_layer");
  // or
  const experiment = useExperiment("my_experiment");

  return (
    <div>
      Title: {layer.get('title', 'Fallback Title')}
      {/* or */}
      Title: {experiment.get('title', 'Fallback Title')}
    </div>
  );
}

In an App Router app, you need to use the use client directive to ensure your logic runs on the frontend.

Parameter Stores

Parameter Stores hold a set of parameters for your app. These parameters can be remapped dynamically from a static value to a Statsig entity (Feature Gates, Experiments, and Layers), so you can decouple your code from the configuration in Statsig. Refer to Parameter Stores for details.

tsx

'use client';

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

export default function Home() {
  const store = useParameterStore("my_param_store");

  return (
    <div>
      Title: {store.get('title', 'Fallback Title')}
    </div>
  );
}

In an App Router app, you need to use the use client directive to ensure your logic runs on the frontend.

Logging an Event

After setting up a Feature Gate or Experiment, you may want to track custom events to see how new features or experiment groups affect those events. Call the Log Event API for the event. You can also provide a value and metadata object to be logged with the event:

tsx

'use client';

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

export default function Home() {
  const { client } = useStatsigClient();

  return (
    <div>
      <button onClick={() => client.logEvent("my_custom_event")}>
        Click Me
      </button>
    </div>
  );
}

In an App Router app, you need to use the use client directive to ensure your logic runs on the frontend.

Flushing Logged Events

flush() sends queued events immediately. Use shutdown() when your app is exiting.

tsx

'use client';

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

export default function Home() {
  const { client } = useStatsigClient();

  return (
    <div>
      <button
        onClick={async () => {
          await client.flush();
        }}
      >
        Flush Events
      </button>
    </div>
  );
}

In an App Router app, you need to use the use client directive to ensure your logic runs on the frontend.

Session Replay

tsx

'use client';

import { StatsigProvider } from '@statsig/react-bindings';
import { StatsigSessionReplayPlugin } from '@statsig/session-replay';

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <StatsigProvider
      sdkKey={process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY!}
      user={{ userID: 'a-user' }}
      options={{ plugins: [new StatsigSessionReplayPlugin()] }}
    >
      {children}
    </StatsigProvider>
  );
}

Web Analytics / Auto Capture

By including the @statsig/web-analytics package in your project, you can automatically capture common web events like clicks and page views.For more information on filtering events, enabling console log capture, and other configuration options available in web analytics, refer to the Web Analytics Configuration documentation.

tsx

'use client';

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

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <StatsigProvider
      sdkKey={process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY!}
      user={{ userID: 'a-user' }}
      options={{ plugins: [new StatsigAutoCapturePlugin()] }}
    >
      {children}
    </StatsigProvider>
  );
}

Stable ID

Stable ID provides a consistent device identifier. It lets you run logged-out experiments and target gates at the device level.

How Stable ID Works

On first initialization, the SDK generates a Stable ID and stores it in localStorage under statsig.stable_id.<SDK_KEY_HASH>.
Subsequent sessions reuse the stored value. Each client SDK key has its own Stable ID entry.
Local storage is scoped per domain, so cross-domain usage requires sharing the value manually (see below).

Reading the Stable ID

tsx

const context = client.getContext();
console.log('Statsig StableID:', context.stableID);

Overriding the Stable ID

Provide a custom Stable ID through StatsigUser.customIDs.stableID if you already manage a durable device identifier.

tsx

import { StatsigClient, StatsigUser } from '@statsig/js-client';

const userWithStableID: StatsigUser = {
  customIDs: {
    stableID: 'my-custom-stable-id',
  },
};

const client = new StatsigClient('client-xyz', userWithStableID);
await client.updateUserAsync(userWithStableID);

When you override the Stable ID, it is persisted to local storage, so subsequent sessions reuse your custom value.

Add this helper script before initializing the SDK and then copy the stored value onto your user object.

html

<!-- cross domain id script -->
<script>!function(){let t="STATSIG_LOCAL_STORAGE_STABLE_ID";function e(){if(crypto&&crypto.randomUUID)return crypto.randomUUID();let t=()=>Math.floor(65536*Math.random()).toString(16).padStart(4,"0");return`$\{t()\}${t()}-$\{t()\}-4${t().substring(1)}-$\{t()\}-${t()}$\{t()\}${t()}`}let i=null,n=localStorage.getItem(t)||null;if(document.cookie.match(/statsiguuid=([\w-]+);?/)&&([,i]=document.cookie.match(/statsiguuid=([\w-]+);?/)),i&&n&&i===n);else if(i&&n&&i!==n)localStorage.setItem(t,i);else if(i&&!n)localStorage.setItem(t,i);else{let o=e();localStorage.setItem(t,o),function t(i){let n=new Date;n.setMonth(n.getMonth()+12);let o=window.location.host.split(".");o.length>2&&o.shift();let s=`.$\{o.join(".")\}`;document.cookie=`statsiguuid=${i||e()};Expires=$\{n\};Domain=${s};Path=/`}(o)}}();</script>

<!-- Manually attach stableID to user object -->
<script>
const userObj = {};
if (localStorage.getItem('STATSIG_LOCAL_STORAGE_STABLE_ID')) {
  userObj.customIDs = {
    stableID: localStorage.getItem('STATSIG_LOCAL_STORAGE_STABLE_ID'),
  };
}
const client = new Statsig.StatsigClient('<client-sdk-key>', userObj);
</script>

<small> (Use this script at your discretion and test thoroughly.) </small>

Aligning Stable ID Between Client and Server

To share Stable ID with a backend Statsig SDK, send the value with requests and persist it server-side when missing. The server can bootstrap the client with the same Stable ID.

tsx

// Server: ensure Stable ID exists, then return initialize response for the client
const values = Statsig.getClientInitializeResponse(user, YOUR_CLIENT_KEY, {
  hash: 'djb2',
});

// Client: apply the server-provided values and initialize synchronously
const { values, user: verifiedUser } = await fetch('/init-statsig-client', {
  method: 'POST',
  body: loadUserData(),
}).then((res) => res.json());

const myClient = new StatsigClient(YOUR_CLIENT_KEY, verifiedUser);
myClient.dataAdapter.setData(values);
myClient.initializeSync();

Lifecycle & Advanced Usage

Shutting Statsig Down

The SDK keeps event logs in the client cache and flushes them periodically to save data and battery usage. Because of this, the SDK may not have flushed some events when your app shuts down.

To ensure all logged events are flushed or saved locally, shut down Statsig when your app is closing:

tsx

'use client';

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

export default function Home() {
  const { client } = useStatsigClient();

  useEffect(() => {
    return () => {
      void client.shutdown();
    };
  }, [client]);

  return null;
}

In an App Router app, you need to use the use client directive to ensure your logic runs on the frontend.

Advanced Setup

Client Bootstrapping (Recommended)

import { Statsig, StatsigUser } from '@statsig/statsig-node-core';

export async function POST(request: Request): Promise<Response> {
  const body = await request.json();
  const user = new StatsigUser(body?.user ?? {});

  // Ensure server SDK is initialized at startup
  // await Statsig.initialize(process.env.STATSIG_SERVER_KEY!);

  const values = Statsig.getClientInitializeResponse(user, {
    hashAlgorithm: 'djb2',
  });
  return new Response(JSON.stringify(values), { status: 200 });
}

tsx

import { StatsigBootstrapProvider } from '@statsig/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  const user = { userID: 'user-123' };
  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>
  );
}

Proxying Network Traffic (Optional)

// Note: Using generic path names like "proxy" instead of "statsig-proxy"
// to prevent ad blockers from blocking these requests
import { generateBootstrapValues } from './statsig-backend';

export async function POST(request: Request): Promise<Response> {
  const json = await request.json();
  if (!json || typeof json !== 'object') {
    return new Response(null, { status: 400 });
  }
  const data = await generateBootstrapValues();
  return new Response(data);
}

// Note: Using generic path names like "search" instead of "log_event" or "events"
// to prevent ad blockers from blocking these requests
type ExtendedRequestInit = RequestInit & { duplex?: 'half' | 'full' };

export async function POST(request: Request): Promise<Response> {
  const tail = request.url.split('?').pop();
  const logEventUrl = `https://events.statsigapi.net/v1/log_event?${tail}`;
  const fetchOptions: ExtendedRequestInit = {
    method: 'POST',
    body: request.body,
    headers: request.headers,
    duplex: 'half',
  };
  return fetch(logEventUrl, fetchOptions);
}

// Assign URLs when creating the client
const inst = new StatsigClient(clientSdkKey, user, {
  networkConfig: {
    logEventUrl: '/api/proxy/search',
    initializeUrl: '/api/proxy/initialize',
    logEventCompressionMode: 'Forced',
  },
  disableCompression: true,
  disableStatsigEncoding: true,
});

Static Site Generation (SSG)

Static Site Generation renders HTML at build time. Because static HTML can't respond to per-user values, experimenting on SSG content requires one of these patterns:

Use Edge Middleware with Statsig's Edge Config Adapter for zero-latency redirects.
Isolate Statsig usage to hydrated client components only.

tsx

// Create a single client and share it across multiple StatsigProviders
const myStatsigClient = new StatsigClient(YOUR_SDK_KEY, user, options);
await myStatsigClient.initializeAsync();

<StatsigProvider client={myStatsigClient}>
  <YourComponent />
</StatsigProvider>

<StatsigProvider client={myStatsigClient}>
  <AnotherComponent />
</StatsigProvider>

Statsig Options

loggingEnabledLoggingEnabledOption

Controls logging behavior.

browser-only (default): log events from browser environments.
disabled: never send events.
always: log in every environment, including non-browser contexts.

disableLoggingboolean

Use loggingEnabled: 'disabled' instead.

disableStableIDboolean

Skip generating a device-level Stable ID.

disableEvaluationMemoizationboolean

Recompute every evaluation instead of using the memoized result.

initialSessionIDstring

Override the generated session ID.

enableCookiesboolean

Persist Stable ID in cookies for cross-domain tracking.

disableStorageboolean

Prevent any local storage writes (disables caching).

networkConfigNetworkConfig

Override network endpoints per request type.

environmentStatsigEnvironment

Set environment-wide defaults (for example { tier: 'staging' }).

logLevelLogLevel

Console verbosity.

loggingBufferMaxSizenumber

Max events per log batch.

loggingIntervalMsnumber

Interval between automatic flushes.

overrideAdapterOverrideAdapter

Modify evaluations before returning them.

includeCurrentPageUrlWithEventsboolean

Attach the current page URL to logged events.

disableStatsigEncodingboolean

Send requests without Statsig-specific encoding.

logEventCompressionModeLogEventCompressionMode

Control compression for batched events.

disableCompressionboolean

Use logEventCompressionMode instead.

dataAdapterEvaluationsDataAdapter

Provide a custom data adapter to control caching/fetching.

customUserCacheKeyFuncCustomCacheKeyGenerator

Override cache key generation for stored evaluations.

Additional Resources

Was this helpful?

Next.js Client SDK

Set Up the SDK

AI-powered Setup

Manual Setup

Set environment variables

Install packages

Add the StatsigBootstrapProvider

Use the SDK

Checking a Feature Flag/Gate

Reading a Dynamic Config

Getting a Layer/Experiment

Parameter Stores

Logging an Event

Flushing Logged Events

Session Replay

Web Analytics / Auto Capture

Stable ID

How Stable ID Works

Reading the Stable ID

Overriding the Stable ID

Sharing Stable ID Across Subdomains

Aligning Stable ID Between Client and Server

Lifecycle & Advanced Usage

Shutting Statsig Down

Advanced Setup

Client Bootstrapping (Recommended)

Proxying Network Traffic (Optional)

Static Site Generation (SSG)

Statsig Options

Network Config Options

Additional Resources