Integrate FlagSync feature flags into Next.js applications with Vercel Flags.
@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.
Initialize the Client
client
and export a boolean adapter
helper:Define Your Feature Flag
flag()
function to define your feature flag, and connect it to the adapter
.Use the Flag in a Server Component
identify
function that returns an FsUserContext
object. Pass this function to Vercel’s flag()
function.
key
in FsUserContext
is unique and persistent for accurate MAU tracking and consistent flag evaluations. See User Context Best Practices for details.Create a Helper Function
identify
with the createIdentify
helper, linking flags to user contexts.Set Up Identification
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. Set Cookies in Middleware (Optional)
getFlagSyncUserContext
.Use the Helper in Flag Definitions
identify
to the flag definition. This connects flag evaluation to the user context.createTypedFlag
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.
Generate Types
flags.d.ts
file, mapping your flag keys to their specific data types.Build the Type-Safe Flag Function
flag
function with the createTypedFlag
factory.Define Your Flags
adapter
when using the typed flag function.Use in a Server Component
flag
function from flags/next
and provide it with an adapter that has been pre-typed.
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);
Use the Correct Adapter
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.Use in a Server Component
track
function:
SDK_UPDATE
: Emitted when flags are updatedSDK_READY
: Emitted when the SDK is readyERROR
: Emitted when an error occurs during initializationSDK_UPDATE
does not fire if syncing is disabled.FsConfig
interface:
key
in FsUserContext
is unique and persistent for accurate MAU tracking and consistent flag evaluations. See User Context Best Practices for details.sync
object: stream
, poll
, or off
.
Stream (Default)
Polling
Off
stream
/poll
/off
) based on your application’s needs.FLAGSYNC_SDK_KEY
: Your server-side FlagSync SDK key (required)