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.
Installation
Install the SDK and required dependencies with your preferred package manager: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 a boolean adapter
helper:@/lib/flagsync
2
Define Your Feature Flag
Use the
flag()
function to define your feature flag, and connect it to the adapter
.@/lib/flagsync/flags
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
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
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 customidentify
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.1
Create a Helper Function
Create
identify
with the createIdentify
helper, linking flags to user contexts.@/lib/flagsync
2
Set Up Identification
Create a helper function to construct the user context from request cookies, headers, or your application’s auth system.Adjust the file below to meet your needs.
@/lib/flagsync/user-context
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)
Use middleware to set user identification cookies, simplifying context retrieval in
getFlagSyncUserContext
.middleware.ts
4
Use the Helper in Flag Definitions
Pass
identify
to the flag definition. This connects flag evaluation to the user context.@/lib/flagsync/flags
Usage
Evaluate Flags
The are two distinct approaches for evaluating flags, each with different setup requirements and type-safety guarantees.- With the FlagSync CLI (Recommended): This approach provides maximum type safety. It automatically generates types that validate your flag keys and infer their specific return values.
- Manual Typing: If you aren’t using the CLI, this method still provides strong type safety for a flag’s return value, but requires you to create and manage type-specific adapters manually.
FlagSync CLI
When using the CLI, you must use thecreateTypedFlag
function from the @flagsync/nextjs-sdk
to build a type-safe flag function.
This approach provides full type safety: from key validation to inferred return values, which isn’t possible with the native flags/next
package as it’s unaware of your custom types.
1
Generate Types
First, run the FlagSync CLI to generate a
flags.d.ts
file, mapping your flag keys to their specific data types.gen/flags.d.ts
2
Build the Type-Safe Flag Function
Create and export a
flag
function with the createTypedFlag
factory.@lib/flagsync
3
Define Your Flags
Now you can define all your flags. Thanks to the generated types, you’ll get full autocompletion for keys, and TypeScript will automatically infer the correct return type for each flag.
@lib/flagsync/flags
There’s no need for an
adapter
when using the typed flag function.4
Use in a Server Component
Await the flag definition in Server Components:
app/page.tsx
An Impression is automatically registered when you evaluate the flag.
Manual Typing
If you’re not using the FlagSync CLI, you can still achieve type safety on your flag’s return values. This approach requires you to manually specify each flag’s expected type by creating and using type-specific adapters. You’ll use the nativeflag
function from flags/next
and provide it with an adapter that has been pre-typed.
1
import {
createClient,
createIdentify,
createAdapter, // Renamed from createTypedFlag for clarity
} from '@flagsync/nextjs-sdk';
import { getContext } from '@/lib/flagsync/user-context';
export const client = createClient({
sdkKey: process.env.FLAGSYNC_SDK_KEY!,
});
// The factory creates adapters
const adapterFactory = createAdapter(client);
// Create an adapter for each data type you need
export const boolAdapter = adapterFactory<boolean>();
export const stringAdapter = adapterFactory<string>();
export const numberAdapter = adapterFactory<number>();
export const jsonAdapter = adapterFactory<{ foo: string }>();
export const identify = createIdentify(getContext);
2
Use the Correct Adapter
When defining your flags, import the native
flag
function from flags/next
and pass the corresponding typed adapter you created. This ensures the flag’s return value and defaultValue
are correctly typed.@lib/flagsync/flags
3
Use in a Server Component
Await the flag definition in Server Components:
app/page.tsx
Track Events
Submit user actions with thetrack
function:
api/checkout/route.js
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 updatedSDK_READY
: Emitted when the SDK is readyERROR
: Emitted when an error occurs during initialization
SDK_UPDATE
does not fire if syncing is disabled.Configuration
Configure the SDK with theFsConfig
interface:
Custom Attributes
- Define user attributes for targeting in Flags: User Segments.
- See User Context Identification for the recommended approach to building the context.
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 thesync
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:
2
Polling
Poll the server on an interval:
3
Off
Disable syncing:
Bootstrapping
Initialize the SDK with a set of bootstrap flags: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)