Performant flags and A/B tests
This quickstart shows how to set up the Flags SDK and @flags-sdk/statsig adapter, which are designed for server or middleware environments.
Also refer to the Statsig adapter documentation for a detailed walkthrough.
Install with npm install flags @flags-sdk/statsig
Start by connecting to your existing project and then run vercel link in the CLI to link to the project locally.
Run vercel env pull to make the latest environment variables available to your project locally.
The flags SDK uses an identify function, which provides a user object for any request. The user attributes are used to check the flag against its rules.
Create a flags.ts file, with a simple identify function and a function to check our gate:
// flags.tsimport { statsigAdapter, type StatsigUser } from "@flags-sdk/statsig";import { flag, dedupe } from "flags/next";import type { Identify } from "flags";
export const identify = dedupe((async () => ({ // implement the identify() function to add any additional user properties you'd like, see docs.statsig.com/concepts/user userID: "1234" //for example, set userID})) satisfies Identify<StatsigUser>);
export const createFeatureFlag = (key: string) => flag<boolean, StatsigUser>({ key, adapter: statsigAdapter.featureGate((gate) => gate.value, {exposureLogging: true}), identify,});Open Statsig by clicking on "Open in Statsig" from the Vercel dashboard and create a new Feature Gate (flag) in Statsig called my_feature_flag. This gate will be used by the flag declared in the next step.
Use the feature flag in a `page.tsx file by calling it as a function.
// app/page.tsximport { createFeatureFlag } from "../flags";
export default async function Page() { const enabled = await createFeatureFlag("my_feature_flag")(); //Disabled by default, edit in the Statsig console return <div>myFeatureFlag is {enabled ? "on" : "off"}</div>};That's it! See Statsig adapter for detailed instructions and advanced patterns.
If you'd like to use flags in client-rendered files or use Statsig's built-in analytics, you'll need to add a <StatsigProvider>.
The flags SDK also lets you 'Bootstrap' the Statsig SDK, which is a zero-latency method for fetching frontend feature flags.
Run npm install @statsig/react-bindings to get started.
First, connect an existing project by running vercel link in your terminal, then click the "connect project" button.
Run vercel env pull to make the latest environment variables available to your project locally.
Next, create dynamic-statsig-provider.tsx to setup our Statsig configuration. You can customize this code (for example, add/remove the web analytics plugin), but it should work without modification.
"use client";
import type { Statsig } from "@flags-sdk/statsig";import { StatsigProvider, useClientBootstrapInit,} from "@statsig/react-bindings";import { StatsigAutoCapturePlugin } from '@statsig/web-analytics'; export function DynamicStatsigProvider({ children, datafile,}: { children: React.ReactNode; datafile: Awaited<ReturnType<typeof Statsig.getClientInitializeResponse>>;}) { if (!datafile) throw new Error("Missing datafile"); const client = useClientBootstrapInit( process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY as string, datafile.user, JSON.stringify(datafile), { plugins: [ new StatsigAutoCapturePlugin() ] } //Optional, will add autocaptured web analytics events to Statsig ); return ( <StatsigProvider user={datafile.user} client={client} > {children} </StatsigProvider> );}This file accepts values for a single user from code running on the server side, and adds them to a provider we can access in other client rendered content.
Next, add the provider we created to layout.tsx, to make the functionality available.
// layout.tsx
//add to the top of your fileimport { statsigAdapter } from "@flags-sdk/statsig";import { DynamicStatsigProvider } from "./dynamic-statsig-provider";
// ...any other code you may have
const Statsig = await statsigAdapter.initialize(); const datafile = await Statsig.getClientInitializeResponse({userID: "1234"}, {hash: "djb2",}); // minimal example, you'll want to customize your user object, likely using the flags SDK's identify function
return ( <DynamicStatsigProvider datafile={datafile}> {/* your other elements & children */} </DynamicStatsigProvider> );}
Use Statsig's hooks to access feature flag/ experiment values in any client-rendered file
'use client';// page.tsx, minimal example
import { useGateValue } from "@statsig/react-bindings";
export default function Home() { const flag = useGateValue("my_feature_flag");
return ( <div> Flag Value: {flag ? 'PASSED' : 'FAILED'} </div> );}There are two integration modes to select from:
Create New Statsig Account: Installs the Statsig Native Integration and creates a Statsig account for you if you do not have one already. You get access to Statsig features and plans. Billing is managed through Vercel.
Link Existing Statsig Account: Installs the Statsig Connect Integration. Connects your Vercel project to your existing Statsig account to perform edge config syncing.
Explore Statsig with these resources: