/flags-sdk

name: flags-sdk
description: >
  Guide for feature flags and A/B tests with the Flags SDK (`flags` npm package) and Vercel Flags.
  Use when: declaring flags with `flag()`, using `vercelAdapter` or `vercel flags` CLI
  (add, list, enable, disable, inspect, archive, rm, sdk-keys),
  setting up providers/adapters (Vercel, Statsig, LaunchDarkly, PostHog, GrowthBook, Hypertune,
  Global Config, OpenFeature, Split, Flagsmith, Reflag, Optimizely, or custom adapters),
  implementing precompute patterns for static pages, setting up `identify`/`dedupe`,
  integrating Flags Explorer/Toolbar,
  working with flags in Next.js (App Router, Pages Router, Middleware) or SvelteKit,
  writing custom adapters, or encrypting/decrypting flag values.
  Triggers: feature flags, A/B testing, experimentation, flags SDK, flag adapters, precompute,
  Flags Explorer, feature gates, flag overrides, Vercel Flags, vercel flags CLI, vercel flags add,
  vercel flags list, vercel flags enable, vercel flags disable,
  `flags/next`, `flags/sveltekit`, `flags/react`, `@flags-sdk/*`.

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

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.

Agent workflow: Creating a new flag

When a user asks you to create or add a feature flag, follow these steps in order. Do not leave CLI steps as "next steps" for the user — execute them yourself.

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)
• Does `.vercel/` directory exist? → Project is linked, skip `vercel link` in step 2
• Does `.env.local` contain `FLAGS=`? → Env vars already pulled, skip step 3
• Does `flags.ts` (or `lib/flags.ts`, `src/flags.ts`) exist? → Add to it rather than creating from scratch (step 4)
• Is `@vercel/toolbar` in `package.json`? → Skip toolbar setup (step 6)
• Does `app/.well-known/vercel/flags/route.ts` exist? → Flags Explorer already set up, skip step 7

Steps

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

   pnpm i flags @flags-sdk/vercel

2. **Register the flag with Vercel**: Run `vercel flags add <flag-key> --kind boolean --description "<description>"`.

> **Prerequisite**: The `vercel flags` commands require the Vercel CLI to be installed and authenticated. If the Vercel CLI 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.

Before running `vercel flags add`, verify the project is linked to Vercel. Check for a `.vercel` directory in the project root. If it doesn't exist, run `vercel link` first.

3. **Pull environment variables**: Run `vercel env pull` to write `FLAGS` and `FLAGS_SECRET` to `.env.local`. Without these environment variables, `vercelAdapter` will not be able to evaluate flags. This step is **mandatory** after creating a flag.

4. **Declare the flag in code**: Add it to `flags.ts` (or create the file if it doesn't exist) using `vercelAdapter`:

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

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

5. **Use the flag**: Call it in your page or component and conditionally render based on the result:

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

   export default async function Page() {
     const enabled = await myFlag();
     return <div>{enabled ? 'Feature on' : 'Feature off'}</div>;
   }

6. **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.

7. **Set up Flags Explorer** (if not already present): Create `app/.well-kno