Getting Started

Getting Started with Vercel Flags

Last updated March 6, 2026

This guide walks you through creating a feature flag in the Vercel Dashboard and evaluating it in your application. By the end you'll have a working flag that you can toggle from the dashboard.

AI Assistance

Help me set up Vercel Flags in this project. First, make sure the Vercel CLI is installed (`npm i -g vercel`). If I'm using Claude Code or Cursor, install the Vercel Plugin (`npx plugins add vercel/vercel-plugin`). For other agents, install Vercel Skills (`npx skills add vercel-labs/agent-skills`). Then: 1. Run `vercel link` and `vercel env pull` to get the flag configuration locally. 2. Use `vercel flags` to create a feature flag for the project. Install the flags SDK and configure it to evaluate the flag. 3. Use the flag to conditionally render content in a page. 4. Deploy with `vercel --prod`.

Prerequisites

A Next.js project connected to Vercel.
Vercel CLI installed.

Create a flag in the dashboard
1. Go to your Vercel Dashboard.
2. Open Flags in the sidebar for your project.
3. Create a new flag named marketing-banner.
4. Leave the Type set to Boolean and configure the environment settings to be on for Development and off for Preview and Production.
Pull environment variables
When you create your first flag, Vercel provisions SDK Keys for each environment and stores them in a FLAGS environment variable on your project. Pull them into your local .env.local file:
terminal
```
vercel env pull
```
If your project isn't linked yet, run vercel link first.
Install the required packages
The Flags SDK is a framework-native way to define and evaluate feature flags. It works with any flag provider through adapters. The @flags-sdk/vercel adapter connects it to your Vercel Flags project, and @vercel/flags-core is the evaluation engine used behind the scenes.
Terminal
pnpm i flags @flags-sdk/vercel
If you use an AI coding assistant, you can also install the Flags SDK agent skill to help define, evaluate, and clean up feature flags:
terminal
```
npx skills add vercel/flags --skill flags-sdk
```
OpenFeature is a vendor-neutral standard for feature flags. The @vercel/flags-core package includes the Vercel Flags evaluation engine and the OpenFeature provider.
Terminal
pnpm i @openfeature/server-sdk @vercel/flags-core
The @vercel/flags-core library gives you direct access to the Vercel Flags evaluation engine. Use it when you need full control or are working outside of supported frameworks.
Terminal
pnpm i @vercel/flags-core

Evaluate the flag in your application

Define the flag in a flags.ts file. The vercelAdapter reads the FLAGS environment variable automatically:

flags.ts

import { flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';
 
export const marketingBanner = flag({
  key: 'marketing-banner',
  adapter: vercelAdapter(),
});

Then call the flag in a server component:

app/page.tsx

import { marketingBanner } from '../flags';
 
export default async function Page() {
  const showBanner = await marketingBanner();
 
  return <div>{showBanner ? 'Sale live now!' : 'Welcome'}</div>;
}

See the Flags SDK guide for full setup instructions.

Create a helper that initializes the Vercel provider once and returns a reusable client:

lib/openfeature.ts

import { OpenFeature } from '@openfeature/server-sdk';
import { flagsClient } from '@vercel/flags-core';
import { VercelProvider } from '@vercel/flags-core/openfeature';
 
let initPromise: Promise<void> | null = null;
let initialized = false;
const vercelProvider = new VercelProvider(flagsClient);
 
async function initialize() {
  try {
    await OpenFeature.setProviderAndWait(vercelProvider);
    initialized = true;
  } catch (error) {
    console.error('Failed to initialize provider:', error);
    initPromise = null;
  }
}
 
export async function getOpenFeatureClient() {
  if (initialized) return OpenFeature.getClient();
  if (!initPromise) initPromise = initialize();
  await initPromise;
  return OpenFeature.getClient();
}

Then use it in a server component:

app/page.tsx

import { getOpenFeatureClient } from '../lib/openfeature';
 
export default async function Page() {
  const client = await getOpenFeatureClient();
  const showBanner = await client.getBooleanValue(
    'marketing-banner',
    false,
  );
 
  return <div>{showBanner ? 'Sale live now!' : 'Welcome'}</div>;
}

See the OpenFeature guide for full setup instructions.

Use the flagsClient to evaluate the flag directly:

app/page.tsx

import { flagsClient } from '@vercel/flags-core';
 
export default async function Page() {
  const result = await flagsClient.evaluate<boolean>(
    'marketing-banner',
    false,
  );
 
  return <div>{result.value ? 'Sale live now!' : 'Welcome'}</div>;
}

See the Core Library guide for full setup instructions.

Toggle the flag off for the Development environment in the Vercel Dashboard, then press Review and save and leave a message for the change. Reload the page to see the change.

Add targeting with the identify function

Now that your flag is working, you can add an identify function to pass user and team context for targeting rules. This lets you roll out flags to specific users, plans, or teams from the dashboard.

Update your flags.ts to define your entities and an identify function. The dedupe helper ensures the session is only fetched once per request, even if multiple flags call identify:

flags.ts

import { flag, dedupe } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';
 
type Entities = {
  user?: {
    id: string;
    email: string;
    plan: string;
  };
  team?: {
    id: string;
    name: string;
  };
};
 
const identify = dedupe(async (): Promise<Entities> => {
  const session = await getSession();
  return {
    user: session?.user
      ? {
          id: session.user.id,
          email: session.user.email,
          plan: session.user.plan,
        }
      : undefined,
    team: session?.team
      ? {
          id: session.team.id,
          name: session.team.name,
        }
      : undefined,
  };
});
 
export const marketingBanner = flag({
  key: 'marketing-banner',
  adapter: vercelAdapter(),
  identify,
});

To use these entities in the dashboard, define them as entities so you can build targeting rules based on attributes like user.plan or team.id.

Pass an evaluation context when calling getBooleanValue to provide user and team attributes for targeting:

app/page.tsx

import { getOpenFeatureClient } from '../lib/openfeature';
 
export default async function Page() {
  const session = await getSession();
  const client = await getOpenFeatureClient();
 
  const entities = {
    user: session?.user
      ? { id: session.user.id, email: session.user.email, plan: session.user.plan }
      : undefined,
    team: session?.team
      ? { id: session.team.id, name: session.team.name }
      : undefined,
  };
 
  const showBanner = await client.getBooleanValue(
    'marketing-banner',
    false,
    entities,
  );
 
  return <div>{showBanner ? 'Sale live now!' : 'Welcome'}</div>;
}

To use these entities in the dashboard, define them as entities so you can build targeting rules based on attributes like user.plan or team.id.

Pass entities as the third argument to evaluate to provide user and team attributes for targeting:

app/page.tsx

import { flagsClient } from '@vercel/flags-core';
 
export default async function Page() {
  const session = await getSession();
 
  const entities = {
    user: session?.user
      ? { id: session.user.id, email: session.user.email, plan: session.user.plan }
      : undefined,
    team: session?.team
      ? { id: session.team.id, name: session.team.name }
      : undefined,
  };
 
  const result = await flagsClient.evaluate<boolean>(
    'marketing-banner',
    false,
    entities,
  );
 
  return <div>{result.value ? 'Sale live now!' : 'Welcome'}</div>;
}

To use these entities in the dashboard, define them as entities so you can build targeting rules based on attributes like user.plan or team.id.

Built-in resilience

When you deploy to Vercel, the build process fetches your latest flag definitions once at build time and bundles them into the deployment. This guarantees every function uses the same snapshot during the build, and provides a runtime fallback if the Vercel Flags service is temporarily unreachable. Definitions are only fetched when your project has at least one environment variable containing an SDK key for Vercel Flags.

Learn more about embedded definitions.

Next steps

Your flag is working. Here's what to explore next:

Entities and targeting: Define user attributes and create rules to show flags to specific groups.
Segments: Build reusable audience groups like "Beta Testers" or "Internal Team."
Flags Explorer: Override flags in the Vercel Toolbar during development without affecting other users.
Drafts: Define flags in code first, then promote them in the dashboard when you're ready.
Observability: Track flag evaluations in Runtime Logs and Web Analytics.
Managing flags: Configure rules, environments, and flag lifecycles in the dashboard.

Vercel Flags

Dashboard

Was this helpful?

AI Cloud

Core Platform

Security

Secure

Resources

Learn

Frameworks

Company

SDKs

Use Cases

Company

Community

Learn

Open Source

Use Cases

Tools

Users

Getting Started with Vercel Flags

Prerequisites

Create a flag in the dashboard

Pull environment variables

Install the required packages

Evaluate the flag in your application

Add targeting with the identify function

Built-in resilience

Next steps

Secure

Resources

Learn

Frameworks

SDKs

Use Cases

Company

Community