> ## Documentation Index > Fetch the complete documentation index at: https://statsig-4b2ff144-devin-1763168466-llm-docs-audit.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 This page explains set up the sdk. ### AI-powered Setup Setup Statsig in 90 seconds by copying this AI prompt into your IDE: ```text expandable Prompt theme={null} # 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 ( {children} ); } // Update app/layout.tsx to wrap children with MyStatsig import MyStatsig from "./my-statsig"; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode }>) { return ( {children} {/* Preserve all existing layout content */} ); } ### 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 ( {/* Preserve all existing pages */} ); } ### 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](https://nextjs.org/docs/pages) & [App Router](https://nextjs.org/docs/app), with some differences in integration patterns. Add the keys to your .env.local file: ````bash .env.local theme={null} # the NEXT_PUBLIC_ prefix is required for this to be available on the client side This page explains the next_public_ prefix is required for this to be available on the client side. NEXT_PUBLIC_STATSIG_CLIENT_KEY=client- STATSIG_SERVER_KEY=secret- ```text For App Router, install the @statsig/next package: ```bash NPM npm i @statsig/next ```text ```bash Yarn yarn add @statsig/next ```text ```bash PNPM pnpm add @statsig/next ```ruby The \ creates both a Statsig Client and Server instance under the hood, and ["bootstraps"](/client/concepts/initialize#2-bootstrap-initialization) 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](#client-bootstrapping-recommended) and [React](/client/React) docs can provide more guidance. Add this component around the content in your root `layout.tsx` file: ```tsx 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 ( {children} ); } ```text Add the keys to your .env.local file: ```bash .env.local # the NEXT_PUBLIC_ prefix is required for this to be available on the client side NEXT_PUBLIC_STATSIG_CLIENT_KEY=client- ```text Install the @statsig/react-bindings package: ```bash NPM npm i @statsig/react-bindings @statsig/web-analytics ```text ```bash Yarn yarn add @statsig/react-bindings @statsig/web-analytics ```text ```bash PNPM pnpm add @statsig/react-bindings @statsig/web-analytics ```text To integrate Statsig into your Page Router app you can add the `StatsigProvider` to your `_app.tsx` file. There is a [full example](https://github.com/statsig-io/js-client-monorepo/tree/main/samples/next-js-pages-router-sample) in the samples directory of the javascript sdk. ```tsx 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 ( ); } ```` See the [User (StatsigUser)](/concepts/user) 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-flags/overview). 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 theme={null} 'use client'; import { useGateValue } from "@statsig/react-bindings"; export default function Home() { const gate = useGateValue("my_gate"); return (
Gate Value: {gate ? 'PASSED' : 'FAILED'}
); } ```ruby In an App Router app, you need to use the [`use client` directive](https://nextjs.org/docs/app/building-your-application/rendering/client-components) to ensure your logic runs on the frontend. ```tsx import { useGateValue } from "@statsig/react-bindings"; export default function Home() { const gate = useGateValue("my_gate"); return (
Gate Value: {gate ? 'PASSED' : 'FAILED'}
); } ```` ### Reading a Dynamic Config Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, **Dynamic Configs** can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example: ````tsx theme={null} 'use client'; import { useDynamicConfig } from "@statsig/react-bindings"; export default function Home() { const config = useDynamicConfig("my_dynamic_config"); return (
Title: {config.get('title', 'Fallback Title')}
); } ```ruby In an App Router app, you need to use the [`use client` directive](https://nextjs.org/docs/app/building-your-application/rendering/client-components) to ensure your logic runs on the frontend. ```tsx import { useDynamicConfig } from "@statsig/react-bindings"; export default function Home() { const config = useDynamicConfig("my_dynamic_config"); return (
Title: {config.get('title', 'Fallback Title')}
); } ```` ### Getting a Layer/Experiment Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse. ````tsx theme={null} '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 (
Title: {layer.get('title', 'Fallback Title')} {/* or */} Title: {experiment.get('title', 'Fallback Title')}
); } ```ruby In an App Router app, you need to use the [`use client` directive](https://nextjs.org/docs/app/building-your-application/rendering/client-components) to ensure your logic runs on the frontend. ```tsx import { useExperiment, useLayer} from "@statsig/react-bindings"; export default function Home() { const layer = useLayer("my_experiment_layer"); // or const experiment = useExperiment("my_experiment"); return (
Title: {layer.get('title', 'Fallback Title')} {/* or */} Title: {experiment.get('title', 'Fallback Title')}
); } ```` ## Parameter Stores Parameter Stores hold a set of parameters for your mobile app. These parameters can be remapped on-the-fly from a static value to a Statsig entity (Feature Gates, Experiments, and Layers), so you can decouple your code from the configuration in Statsig. Read more about Param Stores [here](/client/concepts/parameter-stores). ````tsx theme={null} 'use client'; import { useParameterStore} from "@statsig/react-bindings"; export default function Home() { const store = useParameterStore("my_param_store"); return (
Title: {store.get('title', 'Fallback Title')}
); } ```ruby In an App Router app, you need to use the [`use client` directive](https://nextjs.org/docs/app/building-your-application/rendering/client-components) to ensure your logic runs on the frontend. ```tsx import { useParameterStore} from "@statsig/react-bindings"; export default function Home() { const store = useParameterStore("my_param_store"); return (
Title: {store.get('title', 'Fallback Title')}
); } ```` ### Logging an Event Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event: ````tsx theme={null} 'use client'; import { useStatsigClient } from "@statsig/react-bindings"; export default function Home() { const { client } = useStatsigClient(); return (
); } ```ruby In an App Router app, you need to use the [`use client` directive](https://nextjs.org/docs/app/building-your-application/rendering/client-components) to ensure your logic runs on the frontend. ```tsx import { useStatsigClient } from "@statsig/react-bindings"; export default function Home() { const { client } = useStatsigClient(); return (
); } ```` ## Session Replay ````tsx theme={null} 'use client'; import { StatsigProvider } from '@statsig/react-bindings'; import { StatsigSessionReplayPlugin } from '@statsig/session-replay'; export default function App({ children }: { children: React.ReactNode }) { return ( {children} ); } ```text ```tsx import { StatsigProvider } from '@statsig/react-bindings'; import { StatsigSessionReplayPlugin } from '@statsig/session-replay'; export default function App({ Component, pageProps }) { return ( ); } ```` ## Web Analytics / Auto Capture By including the [`@statsig/web-analytics`](https://www.npmjs.com/package/@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, see the [Web Analytics Configuration](/webanalytics/overview#event-filtering-and-console-configuration) documentation. ````tsx theme={null} 'use client'; import { StatsigProvider } from '@statsig/react-bindings'; import { StatsigAutoCapturePlugin } from '@statsig/web-analytics'; export default function App({ children }: { children: React.ReactNode }) { return ( {children} ); } ```text ```tsx import { StatsigProvider } from '@statsig/react-bindings'; import { StatsigAutoCapturePlugin } from '@statsig/web-analytics'; export default function App({ Component, pageProps }) { return ( ); } ```` ## Advanced Setup ### Client Bootstrapping (Recommended) ````ts app/api/statsig-bootstrap/route.ts theme={null} import { Statsig, StatsigUser } from '@statsig/statsig-node-core'; export async function POST(request: Request): Promise { 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 }); } ```text ```tsx app/layout.tsx import { StatsigBootstrapProvider } from '@statsig/next'; export default function RootLayout({ children }: { children: React.ReactNode }) { const user = { userID: 'user-123' }; return ( {children} ); } ```text ```ts pages/api/statsig-bootstrap.ts import type { NextApiRequest, NextApiResponse } from 'next'; import { Statsig, StatsigUser } from 'statsig-node'; // legacy Node SDK for pages router export default async function handler( req: NextApiRequest, res: NextApiResponse, ) { if (req.method !== 'POST') { res.status(400).send('/statsig-bootstrap only supports POST'); return; } // Ensure server SDK is initialized at startup // await Statsig.initialize(process.env.STATSIG_SERVER_KEY!); const { user } = JSON.parse(req.body) as { user: StatsigUser }; const values = Statsig.getClientInitializeResponse(user, { hash: 'djb2' }); res.status(200).send(JSON.stringify(values)); } ```text ```tsx pages/_app.tsx import type { AppProps } from 'next/app'; import { StatsigProvider } from '@statsig/react-bindings'; import { StatsigClient } from '@statsig/js-client'; import { useEffect, useMemo, useState } from 'react'; export default function App({ Component, pageProps }: AppProps) { const user = useMemo(() => ({ userID: 'a-user' }), []); const [client, setClient] = useState(null); useEffect(() => { (async () => { const res = await fetch('/api/statsig-bootstrap', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ user }), }); const initializeValues = await res.json(); const inst = new StatsigClient( process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY!, user, { initializeValues }, ); await inst.initializeAsync(); setClient(inst); })(); }, [user]); if (!client) { return null; } return ( ); } ```` ### Proxying Network Traffic (Optional) ## Statsig Site Generation (SSG) Vercel's Static Site Generation renders HTML at build time. Because static HTML can't be responsive to per-user values, experimenting on SSG content requires one of these patterns: * Use Vercel Edge Middleware with Statsig's Edge Config Adapter for zero-latency redirects. * Isolate Statsig usage to hydrated client components only. ```tsx theme={null} // Create a single client and share it across multiple StatsigProviders const myStatsigClient = new StatsigClient(YOUR_SDK_KEY, user, options); await myStatsigClient.initializeAsync(); ``` ## Statsig Options This page explains statsig options. Controls logging behavior. * `browser-only` (default): log events from browser environments. * `disabled`: never send events. * `always`: log in every environment, including non-browser contexts. Use `loggingEnabled: 'disabled'` instead. Skip generating a device-level Stable ID. Recompute every evaluation instead of using the memoized result. Override the generated session ID. Persist Stable ID in cookies for cross-domain tracking. Prevent any local storage writes (disables caching). Override network endpoints per request type. Set environment-wide defaults (for example `{ tier: 'staging' }`). Console verbosity. Max events per log batch. Interval between automatic flushes. Modify evaluations before returning them. Attach the current page URL to logged events. Send requests without Statsig-specific encoding. Control compression for batched events. Use `logEventCompressionMode` instead. Provide a custom data adapter to control caching/fetching. Override cache key generation for stored evaluations. Base URL for all requests (append `/v1`). Endpoint for event uploads. Fallback endpoints for event uploads. Request timeout in milliseconds. Disable all outbound requests; combine with `loggingEnabled: 'disabled'` to silence log warnings. Provide custom transport (e.g., Axios). Endpoint for initialization requests. ## Additional Resources * Docusaurus Next.js reference * JavaScript Client SDK * React Client SDK * Initialization Concepts