---
title: Vercel Flags
url: "https://flags-sdk.dev/docs/providers/vercel"
docs_index: /llms.txt
lastUpdated: 2026-11-02
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

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. Use OIDC for this project's flags. To read another same-team project's flags, use `@flags-sdk/vercel` version 1.6.0 or later, configure a Project Connection, then use `createVercelAdapter({ projectId })` with the source project's ID. For an app outside Vercel, pass an SDK key to `createVercelAdapter`.

[Vercel Flags is now available — read the announcement](https://vercel.com/blog/vercel-flags-platform-native-feature-flags)

[Learn more about Vercel Flags](https://vercel.com/docs/flags/vercel-flags)

## Installation

Install the Vercel adapter package:

```bash
pnpm i flags @flags-sdk/vercel
```

If you use an AI coding assistant, install the agent skills: `flags-sdk` for the code, and `vercel-flags` for planning flags, the `vercel flags` CLI, rollouts, and experiments:

```bash
npx skills add vercel/flags --skill flags-sdk --skill vercel-flags
```

## Quickstart

### 1. Create a feature flag in Vercel

Create your first feature flag in the Vercel dashboard:

[Create Flag](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fflags%3Fcreate%3D1\&title=Go+to+Vercel+Flags)

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.

### 2. 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](https://vercel.com/docs/cli):

```bash
vercel env pull
```

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

### 3. Declare the flag in your code

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

```ts title="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](#sdk-keys) for when you need one.

### 4. Use the flag

Call the flag as a function to resolve its value:

```tsx title="app/hello-world/page.tsx#next"
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.

```ts title="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](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fflags%2F%5Bentities\&title=Go+to+Vercel+Flags)

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](https://vercel.com/docs/flags/flags-explorer) provides a UI for viewing and overriding flags during development and testing.

To enable full integration, create a flags discovery endpoint:

```ts title="app/.well-known/vercel/flags/route.ts#next"
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

### Read a connected project's flags

Project Connections let your project read flags from another project in the same team without an SDK key. With the Flags SDK, use `@flags-sdk/vercel` version 1.6.0 or later. In the source project's **Flags → Connections** page, grant your project access. Then pass the source project's ID to `createVercelAdapter`:

```ts title="flags.ts"
import { flag } from 'flags/next';
import { createVercelAdapter } from '@flags-sdk/vercel';

const sharedAdapter = createVercelAdapter({ projectId: 'prj_source' });

export const sharedFeature = flag({
  key: 'shared-feature',
  adapter: sharedAdapter,
  defaultValue: false,
});
```

The adapter uses your project's OIDC token. Keep `vercelAdapter` for flags owned by your project. For local development, run `vercel env pull` in your project.

Connections grant read access across environments. Your deployment's token selects the source environment: production reads production, preview reads preview, and local development reads development. Custom environments use preview. The `projectId` option cannot be combined with an SDK key.

If you use the [core library](https://vercel.com/docs/flags/vercel-flags/sdks/core) directly, use `@vercel/flags-core` version 1.11.0 or later. The adapter includes the required core library version.

Managing connections with `vercel flags connections` requires Vercel CLI version 63.0.0 or later. See [Project Connections](https://vercel.com/docs/flags/vercel-flags/project-connections) for permissions and connection management.

### SDK keys

You do not need an SDK key when your app runs on Vercel and reads its own or a connected project's flags. Use an SDK key for apps outside Vercel or when you need to select an environment explicitly. Create the key in the Vercel dashboard and pass it to `createVercelAdapter`:

```ts title="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](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys)

## Additional resources

- [Vercel Flags](https://vercel.com/docs/flags/vercel-flags)
- [@flags-sdk/vercel](https://github.com/vercel/flags/tree/main/packages/adapter-vercel)

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)