/flags-sdk

name: flags-sdk
description: >
  Set up and use feature flags and A/B tests with the Flags SDK (`flags` npm package) and Vercel Flags.
  Use when installing or configuring the SDK, adding a new or existing flag, wiring `vercelAdapter`
  (OIDC or SDK keys), declaring flags with `flag()`, using the `vercel flags` CLI (create, inspect, list,
  enable, disable, set, update, split, rollout, rules, segments, use-targeting, evaluations, versions,
  open, archive, unarchive, rm, sdk-keys, override, prepare), setting up providers/adapters (Vercel, Statsig, LaunchDarkly,
  PostHog, GrowthBook, Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom),
  precompute, `identify`/`dedupe`, Flags Explorer/Toolbar, Next.js or SvelteKit, or encrypting flag values.
  Triggers: feature flags, feature gates, A/B testing, experimentation, gradual rollout, traffic split,
  targeting rules, flag overrides, precompute, Flags Explorer, Vercel Flags, vercel flags CLI,
  `flags/next`, `flags/sveltekit`, `flags/react`, `@flags-sdk/*`.

Set up and use the Flags SDK

The Flags SDK (`flags` npm package) is a feature flags toolkit for Next.js and SvelteKit. It turns each feature flag into a callable function, works with any flag provider via adapters, and keeps pages static using the precompute pattern. Vercel Flags is the first-party provider, letting you manage flags from the Vercel dashboard or the `vercel flags` CLI.

• Docs: https://flags-sdk.dev
• Repo: https://github.com/vercel/flags

When the user asks to install, configure, or set up feature flags, follow [Set up the SDK](#set-up-the-sdk) (including `vercel env pull` when `.env.local` is missing). When they ask to create or add a flag, follow [Create a flag](#create-a-flag). A request is CLI-only when the user asks to inspect, create, or change a remote flag and the request involves no code; then follow [CLI-only flag management](#cli-only-flag-management). Inside an app repository, treat an ambiguous request as the full flow. Do not leave CLI steps as "next steps" for the user — execute them yourself.

Core concepts

Flags as code

Each flag is declared as a function. No string keys at call sites:

import { flag } from 'flags/next';

export const exampleFlag = flag({
  key: 'example-flag',
  decide() { return false; },
});

const value = await exampleFlag();

Server-side evaluation

Flags evaluate server-side to avoid layout shift, keep pages static, and maintain confidentiality. Combine routing middleware with the precompute pattern to serve static variants from CDN.

Adapter pattern

Adapters replace `decide` and `origin` on a flag declaration, connecting your flags to a provider. Vercel Flags (`@flags-sdk/vercel`) is the first-party adapter. Third-party adapters are available for Statsig, LaunchDarkly, PostHog, and others.

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

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

> **Version note**: The SDK is published as `flags` (renamed from `@vercel/flags`; that old name still appears in changelog history). `flags` 4.2.0+ accepts the adapter factory by reference (`adapter: vercelAdapter`) and resolves it once per declaration. Older versions require calling it (`adapter: vercelAdapter()`). The called form still works on new versions, so prefer the shorthand unless you're targeting `flags` < 4.2.0.

Set up the SDK

One-time project setup. Run this when the Flags SDK is not installed yet, or when Toolbar / Flags Explorer / `.env.local` are missing. Skip any step that is already done.

Before you start

Check the project state to adapt commands and decide which steps you can skip:

• Which lockfile is present (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`)? → Adapt all package manager commands accordingly (`pnpm add`, `npm install`, `yarn add`, `bun add`).
• Is `flags` in `package.json`? → Skip install (step 1)
• Is the project linked? → Skip `vercel link` in step 2
• Does `.env.local` contain `VERCEL_OIDC_TOKEN=` (or a `FLAGS=` SDK key)? → Env vars already pulled, skip step 3
• Is `@vercel/toolbar` in `package.json`? → Skip toolbar setup (step 4)
• Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Skip creating it (step 5)
• Does `app/.well-known/vercel/flags/route.ts` exist? → Flags Explorer already set up, skip step 6

Steps

1. **Install packages** (if not already in `package.json`):

   pnpm i flags @flags-sdk/vercel

2. **Link the project to Vercel** (required for `vercel env pull` and local OIDC token refresh): > **Prerequisite**: The Vercel CLI must be installed and authenticated. If it is not installed, run `pnpm i -g vercel`. For authentication or linking issues, follow the `vercel-cli` skill if it's already available. If it isn't, suggest the user install it with `npx skills add vercel/vercel@vercel-cli` (don't auto-install it) and rely on `vercel <command> --help` in the meantime.

Verify the link as described in [Project targeting](#project-targeting). If the project is not linked, run `vercel link`.

3. **Pull environment variables**: If `.env.local` lacks `VERCEL_OIDC_TOKEN=`, follow [Pull environment variables](#pull-environment-variables).

4. **Set up the Vercel Toolbar** (if not already present):

• Run `pnpm i @vercel/toolbar`
• Wrap `next.config.ts` with the toolbar plugin
• Render `<VercelToolbar />` in the root layout

See [references/nextjs.md — Toolbar Setup](references/nextjs.md#toolbar-setup) for the full code.

5. **Ensure `flags.ts` exists**: If missing, create `flags.ts` (or `lib/flags.ts` / `src/flags.ts` to match the project) with `export {}` so TypeScript treats it as a module. Flags Explorer imports this file — create it before the discovery route.

6. **Set up Flags Explorer** (if not already present): Create `app/.well-known/vercel/flags/route.ts` — see [Flags Explorer s