/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/*`."
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). 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 fac