​
Overview

The @flagsync/nextjs-sdk integrates into Next.js applications with Vercel Flags for feature management and event tracking—ideal for SSR and static site generation workflows.

npm

View the latest version on npm

GitHub

Explore the source code on GitHub

​
Installation

Install the SDK and required dependencies with your preferred package manager: 
npm install @flagsync/nextjs-sdk flags

​
Quickstart

Integrate FlagSync with Vercel Flags in your Next.js app in just a few steps:
1

Initialize the Client

Create the client and export the adapter helper to be used in your flag definition.
@/lib/flagsync
import {
  createFlagSyncAdapter,
  createFlagSyncClient,
} from '@flagsync/nextjs-sdk';

const client = createFlagSyncClient({
  sdkKey: process.env.FLAGSYNC_SDK_KEY!,
});

export const adapter = createFlagSyncAdapter(client)();
2

Define Your Feature Flag

Use the flag() function to define your feature flag, and connect it to the adapter.
@/lib/flagsync/flags
import { flag } from 'flags/next';
import { adapter } from '@/lib/flagsync';

export const myFlag = flag({
  key: 'my-flag',                         // Unique flag key
  identify: () => ({ key: 'user-123' }),  // See note below
  adapter,
});
See User Context Identification for the recommended approach to building the context.
3

Use the Flag in a Server Component

Call your feature flag like an async function in a Server Component to get the evaluated value.
app/page.tsx
import { myFlag } from '@/lib/flagsync/flags';

export default async function HomePage() {
  const value = await myFlag();

  return <div>{myFlag.key} is {value}</div>;
}

​
Initialization

​
Get Your SDK Key

Find your server-side SDK key in your workspace settings. Keep server-side keys private to protect flag rules.

​
Initialize the SDK

Initialize the FlagSync client singleton with your server-side SDK key:
lib/flagsync.ts
import { createFlagSyncClient } from '@flagsync/nextjs-sdk';

export const client = createFlagSyncClient({
  sdkKey: process.env.FLAGSYNC_SDK_KEY!,
});

​
Wait for Readiness

The SDK automatically initializes during the Next.js App Router lifecycle—no manual waiting is required for Server Components.

​
User Context Identification

Define the user context with a custom identify function that returns an FsUserContext object. Pass this function to Vercel’s flag() function.
User contexts enable personalized flag evaluations via Individual Targeting and consistent experiences during Percentage Rollouts.
Ensure the key in FsUserContext is unique and persistent for accurate MAU tracking and consistent flag evaluations. See User Context Best Practices for details.
import { flag } from 'flags/next';
import { adapter, identify } from '@/lib/flagsync';

export const landingPageLayoutPage = flag({
  key: 'my-flag',
  identify,
  adapter,
});
1

Create a Helper Function

Create identify with the createIdentify helper, linking flags to user contexts. We’ll create getFlagSyncUserContext next.
@/lib/flagsync
import {
  createFlagSyncAdapter,
  createFlagSyncClient,
  createIdentify,
} from '@flagsync/nextjs-sdk';

import { getFlagSyncUserContext } from '@/lib/flagsync/user-context';

const client = createFlagSyncClient({
  sdkKey: process.env.FLAGSYNC_SDK_KEY!,
});

export const adapter = createFlagSyncAdapter(client)();
export const identify = createIdentify(getFlagSyncUserContext);
2

Set Up Identification

Every application will implement this differently, however the example below uses cookies to get the logged-in user.Adjust the file below to meet your needs.
@/lib/flagsync/user-context
import { nanoid } from 'nanoid';
import { dedupe } from 'flags/next';
import type { ReadonlyHeaders, ReadonlyRequestCookies } from 'flags';
import type { NextRequest } from 'next/server';

const generateId = dedupe(async () => nanoid());

type FlagParamsType = {
  cookies: ReadonlyRequestCookies | NextRequest['cookies'],
  headers: ReadonlyHeaders | NextRequest['headers'],
};

// Return the user context (FsUserContext)
export const getFlagSyncUserContext = async (params: FlagParamsType) => {
  const key = await getUserContextKey(params);
  return {
    key,
    attributes: {
      region: params.headers.get('x-region'),
      userAgent: params.headers.get('user-agent')
    }
  };
};

const getUserContextKey = async ({ cookies }: FlagParamsType) => {
  const userId = cookies.get('user-id')?.value;
  if (userId) return userId;

  const visitorId = cookies.get('visitor-id')?.value;
  if (visitorId) return visitorId;

  // Fallback
  return generateId();
};
The key is set using a persistent userId or visitorId from cookies, falling back to a generated ID with nanoid(). For proper MAU tracking and consistent flag evaluations, ensure this key is unique and persistent across requests—see User Context Best Practices.
3

Set Cookies in Middleware (Optional)

Set user and visitor cookies in middleware to simplify context retrieval in getUserContextKey.
middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { nanoid } from 'nanoid';

const jwtSecret = new TextEncoder().encode('your-jwt-secret-key');

export async function middleware(request: NextRequest) {
  const response = NextResponse.next();

  const jwt = request.cookies.get('jwt')?.value;
  const visitorId = request.cookies.get('visitor-id')?.value

  let user;
  if (jwt) {
    const { payload } = await jwtVerify(jwt, jwtSecret);
    user = payload;
  }

  if (user?.userId) {
    response.cookies.set('user-id', user.userId, { maxAge: 60 * 60 * 24 * 7 });
  } else {
    response.cookies.set('visitor-id', visitorId ?? nanoid(), { maxAge: 60 * 60 * 24 * 365 });
  }

  return response;
}

​
Usage

​
Evaluate Flags

Evaluate flags in Server Components using the Vercel Flags flag function, which applies targeting rules, rollouts, and defaults for the user context:
An Impression is automatically registered when you evaluate the flag.
import { myFlag } from '@/app/dashboard/flags';

export default async function DashboardPage() {
  const value = await myFlag();

  return (
    <div>The value of {myFlag.key} is {value}</div>
  );
}

​
Track Events

Submit user actions with the track function:
api/checkout/route.js
import { cookies } from 'next/headers';
import { client, identify } from '@/lib/flagsync';
import { api } from '@/lib/api';

export async function POST(request) {
  const { product } = await request.json();

  const cookieStore = cookies(); // ReadonlyRequestCookies
  const headerStore = headers(); // ReadonlyHeaders

  const context = await identify({
    cookies: cookieStore,
    headers: headerStore
  });

  // Property event
  client.track(context, 'purchase-event', null, product);

  // Time the operation
  const t0 = Date.now();
  const order = await api.makePurchase(request);
  const receipt = await api.sendOrder(order)
  const t1 = Date.now()

  // Numeric event
  client.track(context, 'purchase-duration', t1 - t0);

  return Response.json({ success: true });
}
See Events: Tracking to learn about numeric and property events.

​
SDK Event Listeners

The SDK emits these events for SDK lifecycle management:
  • SDK_UPDATE: Emitted when flags are updated
  • SDK_READY: Emitted when the SDK is ready
  • ERROR: Emitted when an error occurs during initialization
import { FsEvent } from '@flagsync/js-sdk';

// Flag updates
client.on(FsEvent.SDK_UPDATE, () => {
  console.log(`Flags updated at ${new Date().toISOString()}`)
});
SDK_UPDATE does not fire if syncing is disabled.

​
Configuration

Configure the SDK with the FsConfig interface: 
export interface FsConfig {
  sdkKey: string;
  sync?: {
    type?: 'stream' | 'poll' | 'off'; // Optional: Sync strategy
    pollRate?: number;                // Optional: Polling interval in seconds
  };
  tracking?: {
    impressions?: {
      maxQueueSize: number;           // Required: Max impressions queue size
      pushRate: number;               // Required: Impressions push rate
    };
    events?: {
      maxQueueSize: number;           // Required: Max events queue size
      pushRate: number;               // Required: Events push rate
    };
  };
  urls?: {
    sdk?: string;                     // Optional: SDK endpoint URL
  };
  logger?: Partial<ILogger>;          // Optional: Custom logger
  logLevel?: LogLevel;                // Optional: Logging level
  metadata?: Record<string, any>;     // Optional: Additional metadata
}

​
Custom Attributes

const context: FsUserContext = {
  key: 'user-123',
  attributes: {
    plan: 'premium',
    country: 'US',
    userType: 'enterprise'
  }
}
Ensure the key in FsUserContext is unique and persistent for accurate MAU tracking and consistent flag evaluations. See User Context Best Practices for details.

​
Flag Syncing

Configure flag update strategies with the sync object: stream, poll, or off.
By default, flag updates propagate in milliseconds via server-side events (SSE), ensuring the latest values are used in evaluations.
1

Stream (Default)

Stream updates via SSE—flag updates are reevaluated on the server and sent to the client:
createFlagSyncClient({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'stream' // Default
  }
});
2

Polling

Poll the server on an interval:
createFlagSyncClient({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'poll',
    pollRate: 60
  }
});
3

Off

Disable syncing:
createFlagSyncClient({
  sdkKey: 'your-sdk-key',
  sync: {
    type: 'off'
  }
});

​
Bootstrapping

Initialize the SDK with a set of bootstrap flags: 
createFlagSyncClient({
  sdkKey: 'your-sdk-key',
  bootstrap: {
    'my-feature': true,
    'other-feature': false,
  },
});

​
Best Practices

  • Select a sync strategy (stream/poll/off) based on your application’s needs.
  • Follow User Context Identification for simplified context management.
  • Add user attributes for targeted feature rollouts.

​
Environment Variables

Set the following environment variable:
  • FLAGSYNC_SDK_KEY: Your server-side FlagSync SDK key (required)