/flags-sdk

name: flags-sdk
description: "Feature flags, A/B tests, and gradual rollouts in any app or framework. Use whenever the user is planning, adding, or changing a feature flag, toggle, kill switch, experiment, or percentage rollout, or wants to gate or hide a feature for some users, even before a library or provider is chosen. Covers Vercel Flags, the Flags SDK (`flags`, `@flags-sdk/*`), `@vercel/flags-core`, OpenFeature, provider adapters such as Statsig, LaunchDarkly, and PostHog, Flags Explorer, and the `vercel flags` CLI."
summary: "Flags SDK guidance — declare flags with flag(), connect provider adapters, manage Vercel Flags via the vercel flags CLI, precompute static variants, and set up the Flags Explorer."
metadata:
  priority: 6
  docs:
    - "https://vercel.com/docs/flags"
    - "https://flags-sdk.dev"
  sitemap: "https://vercel.com/sitemap.xml"
  pathPatterns:
    - 'flags.ts'
    - 'flags.tsx'
    - 'lib/flags.ts'
    - 'src/flags.ts'
    - 'lib/flags/**'
    - 'src/flags/**'
    - '.well-known/vercel/flags/**'
  importPatterns:
    - 'flags/next'
    - 'flags/sveltekit'
    - 'flags/react'
    - 'flags'
    - '@flags-sdk/*'
    - '@vercel/flags'
  bashPatterns:
    - '\bvercel\s+flags\b'
    - '\bvc\s+flags\b'
    - '\bnpm\s+(install|i|add)\s+[^\n]*\bflags\b'
    - '\bpnpm\s+(install|i|add)\s+[^\n]*\bflags\b'
    - '\bbun\s+(install|i|add)\s+[^\n]*\bflags\b'
    - '\byarn\s+add\s+[^\n]*\bflags\b'
    - '\bnpm\s+(install|i|add)\s+[^\n]*@flags-sdk/'
    - '\bpnpm\s+(install|i|add)\s+[^\n]*@flags-sdk/'
    - '\bbun\s+(install|i|add)\s+[^\n]*@flags-sdk/'
    - '\byarn\s+add\s+[^\n]*@flags-sdk/'
  promptSignals:
    phrases:
      - "feature flag"
      - "feature flags"
      - "flags sdk"
      - "vercel flags"
      - "flags explorer"
      - "feature gate"
      - "feature gating"
      - "a/b test"
      - "a/b testing"
      - "ab test"
      - "ab testing"
      - "flag rollout"
      - "gradual rollout"
      - "percentage rollout"
      - "kill switch"
      - "flag variant"
      - "flag adapter"
      - "precompute flags"
      - "traffic split"
      - "targeting rules"
      - "flag rules"
      - "flag segments"
      - "flag targeting"
      - "flag evaluations"
      - "flag overrides"
      - "existing flag"
    allOf:
      - [flag, rollout]
      - [flag, variant]
      - [flag, toggle]
      - [flag, experiment]
      - [experiment, variant]
      - [split, test]
    anyOf:
      - "flag"
      - "experiment"
      - "experimentation"
      - "rollout"
      - "variant"
    noneOf:
      - "command-line flag"
      - "command line flag"
      - "cli flag"
      - "compiler flag"
      - "flag emoji"
      - "rolling release"
    minScore: 6
retrieval:
  aliases:
    - feature flags
    - feature toggles
    - vercel flags
    - flags sdk
    - a/b testing
  intents:
    - add a feature flag
    - run an a/b test
    - gate a feature
    - roll out gradually
    - manage flags from cli
  entities:
    - Flags SDK
    - Vercel Flags
    - Flags Explorer
    - vercelAdapter
    - precompute
    - FLAGS_SECRET
chainTo:
  -
    pattern: 'precompute\s*\(|generatePermutations|flags/next.*precompute'
    targetSkill: routing-middleware
    message: 'Precompute pattern detected — loading Routing Middleware guidance for the middleware rewrites that serve static flag variants.'
  -
    pattern: '@flags-sdk/(edge|global)-config|create(Edge|Global)ConfigAdapter'
    targetSkill: vercel-storage
    message: 'Global Config flag adapter detected — loading Vercel storage guidance for Global Config setup and limits.'

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 target