Vercel Flags

Vercel Flags is a feature flag provider built into Vercel's platform, allowing you to manage flags directly in your Vercel projects. The @flags-sdk/vercel package connects the Flags SDK to Vercel Flags.

Prompt for coding agents

Connect my existing Flags SDK setup to Vercel Flags. Install @flags-sdk/vercel, run vercel env pull so .env.local has the Vercel OIDC token and FLAGS_SECRET, update my flag declarations to use vercelAdapter, add or reuse an identify function for targeting entities, create the Flags Explorer discovery endpoint, and run the relevant type checks or build when finished. vercelAdapter authenticates with the project's Vercel OIDC token, so do not add a FLAGS SDK key unless the app runs outside Vercel or reads flags from another Vercel project; in that case pass the key to createVercelAdapter.

Vercel Flags is now available — read the announcement

Learn more about Vercel Flags

Installation

Install the Vercel adapter package:

pnpm i flags @flags-sdk/vercel

Quickstart

Create a feature flag in Vercel

Create your first feature flag in the Vercel dashboard:

Create Flag

You can create a boolean feature flag called example-flag for this quickstart.

When you create your first flag, Vercel activates Vercel Flags for the project and creates a FLAGS_SECRET environment variable for each environment. Flags Explorer uses it for flag overrides.

Sync environment variables

Vercel Flags authenticates with the Vercel OpenID Connect (OIDC) token of your project. Deployments receive this token automatically. For local development, pull the environment variables to your .env.local file using Vercel CLI:

vercel env pull

You might need to run vercel link first in case you did not link your project to Vercel yet.

Declare the flag in your code

Use the vercelAdapter to connect your flag declaration to Vercel Flags:

flags.ts

import { flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';

export const exampleFlag = flag({
  key: "example-flag",
  adapter: vercelAdapter
});

The vercelAdapter authenticates with the OIDC token of your project and evaluates the flags of the current environment. If you set a FLAGS environment variable, the adapter uses that SDK key instead. See SDK keys for when you need one.

Use the flag

Call the flag as a function to resolve its value:

app/hello-world/page.tsx

import { exampleFlag } from '../../flags';

export default async function Page() {
  const showExample = await exampleFlag();

  return <div>{showExample ? 'Hello world' : 'Not showing'}</div>
}

You can now toggle the feature flag for the development environment on the Vercel dashboard and you should see the updated flag value locally after reloading the page.

User targeting

Target specific users or groups by providing an identify function that returns context about the current user, team, or other entities.

flags.ts

import { dedupe, flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';

type Entities = {
  team?: { id: string };
  user?: { id: string };
};

// Use dedupe to prevent redundant evaluation context lookups
// https://flags-sdk.dev/frameworks/next/evaluation-context#deduplication
const identify = dedupe(async (): Promise<Entities> => {
  return {
    team: { id: 'team-123' },
    user: { id: 'user-456' },
  };
});

export const exampleFlag = flag<boolean, Entities>({
  key: "example-flag",
  identify,
  adapter: vercelAdapter
});

Configure which entities are available for targeting in your Vercel Flags project:

Configure Entities

This allows you to create targeting rules in Vercel Flags based on your specific entity types (users, teams, organizations, etc.).

Flags Explorer integration

Flags Explorer provides a UI for viewing and overriding flags during development and testing.

To enable full integration, create a flags discovery endpoint:

app/.well-known/vercel/flags/route.ts

import { createFlagsDiscoveryEndpoint } from 'flags/next';
import { getProviderData } from "@flags-sdk/vercel";
import * as flags from '../../../../flags';

export const GET = createFlagsDiscoveryEndpoint(async (request) => {
  return await getProviderData(flags);
});

This endpoint allows Flags Explorer to:

Discover all flags defined in your codebase
Show flag metadata and default values
Enable local overrides during development

Advanced configuration

SDK keys

You do not need an SDK key when your app runs on Vercel and reads the flags of its own project. Use one when the app runs outside Vercel, or when it reads flags from another Vercel project. Create the key in the Vercel dashboard and pass it to createVercelAdapter:

flags.ts

import { flag } from 'flags/next';
import { createVercelAdapter } from '@flags-sdk/vercel';

const customAdapter = createVercelAdapter(
  process.env.CUSTOM_FLAGS_KEY!
);

export const exampleFlag = flag({
  key: "example-flag",
  adapter: customAdapter
});

Learn more about SDK keys