Name: flags-sdk
Author: vercel

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, li

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; its adapter is @flags sdk/vercel . Docs: https://flags sdk.dev Repo: https://github.com/vercel/flags This skill covers the code. Planning a flag, choosing between the Flags SDK, @vercel/flags core , and OpenFeature, and managing flags in the dashboard or with the vercel flags CLI belong to the vercel flags skill. Archiving a flag, deleting it, or removing a variant requires the checks in that skill (remove the code first, confirm no evaluations over the Skew Protection window, archive before rm ); do not run those commands without it. If it is not available, suggest npx skills add vercel/flags@vercel flags (do not auto install) and run vercel flags <cmd help in the meantime. For a project on another framework, @vercel/flags core replaces this SDK ([Core SDK](https://vercel.com/docs/flags/vercel flags/sdks/core)). When the user asks to install, configure, or set up the SDK, follow [Set up the SDK]( set up the sdk) (including vercel env pull when .env.local is missing). When they ask to add a flag to the code, follow [Create a flag]( create a flag) or [Add a flag that already exists on Vercel]( add a flag that already exists on vercel). 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: 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. 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 ): 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 with vercel project inspect non interactive and check the reported owner and project name; a .vercel/ directory alone does not prove a link. If it reports link required , run vercel link . If the user named a project or team and the output differs, stop and ask instead of relinking. 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 setup]( flags explorer setup). Do this only after flags.ts exists. Point the import at the real flags file path (the snippet assumes root flags.ts ). Pull environment variables vercel env pull writes the Development credentials to .env.local : the Vercel OIDC token that vercelAdapter uses locally (deployments receive it automatically, [Getting started](https://vercel.com/docs/flags/vercel flags/quickstart pull local openid connect credentials)) and the Development FLAGS SECRET for Flags Explorer and overrides. Run it when: .env.local lacks VERCEL OIDC TOKEN= (or a FLAGS= SDK key) you created the project's first flag; activating Vercel Flags creates a FLAGS SECRET per environment local evaluation fails with an authentication error; the SDK refreshes an expired token through the linked project, re pulling is the fallback SDK keys ( FLAGS ) are only for apps outside Vercel, custom environments, or flags of another project ([SDK Keys](https://vercel.com/docs/flags/vercel flags/dashboard/sdk keys)). If FLAGS SECRET is still missing after the pull, generate it per [FLAGS SECRET]( flags secret). Create a flag When a user asks you to create or add a feature flag that does not exist on Vercel yet, follow these steps in order. If the flag was already created in the dashboard (the prompt says so, or vercel flags create reports the key exists), follow [Add a flag that already exists on Vercel]( add a flag that already exists on vercel) instead. Before you start Complete [Set up the SDK]( set up the sdk) first if packages, Vercel link, .env.local , Toolbar, flags.ts , or Flags Explorer are missing. Skip steps that are already done. Does .env.local contain VERCEL OIDC TOKEN= ? → Env vars already pulled; see [Pull environment variables]( pull environment variables) if local evaluation fails with an authentication error. Does flags.ts (or lib/flags.ts , src/flags.ts ) exist? → Add to it rather than creating from scratch. Steps 1. Ensure the SDK is set up : Follow [Set up the SDK]( set up the sdk) if needed, then continue. 2. Register the flag with Vercel : Run vercel flags create <flag key kind boolean description "<description " against the linked project, or pass project <name or id and scope <team . Pick the kind to match the flag's type parameter; it cannot be changed later. 3. Pull environment variables : If this is the project's first flag, follow [Pull environment variables]( pull environment variables) again; activation created the FLAGS SECRET . 4. Declare the flag in code : Add it to flags.ts (or create the file if it doesn't exist) using vercelAdapter : 5. Use the flag : Call it in your page or component and conditionally render based on the result: Add a flag that already exists on Vercel Use this flow when the flag was created in the dashboard or by someone else, for example when the prompt says the flag "has already been created" or asks you to run vercel flags inspect . Do not run vercel flags create for an existing key. 1. Ensure the SDK is set up : Follow [Set up the SDK]( set up the sdk) if needed. 2. Read the definition : Run vercel flags inspect <flag key . Note the kind, the variants (value and label), the description, and what each environment serves. 3. Pull environment variables : If .env.local lacks VERCEL OIDC TOKEN= , follow [Pull environment variables]( pull environment variables). 4. Declare the flag : Add it to flags.ts with vercelAdapter . Map the inspect output: key : the flag key exactly as printed kind → type parameter: boolean → flag<boolean , string → flag<string , number → flag<number , json → flag<YourType description : copy from inspect defaultValue : the value to serve when the flag is archived or evaluation fails (usually what production serves today) options : optional; mirror the variants when you use precompute or want them listed in Flags Explorer identify : add or reuse one when the flag has targeting, using the entity attributes configured in the dashboard (see [Flag with evaluation context]( flag with evaluation context)) 5. Use the flag as in [Create a flag]( create a flag) step 5. Vercel Flags adapter @flags sdk/vercel connects flag() declarations to Vercel Flags. vercelAdapter authenticates with the project's Vercel OIDC token and evaluates the configuration of the current environment; SDK keys ( FLAGS ) are for manual authentication only: apps outside Vercel, custom environments, or flags of another project ([SDK Keys](https://vercel.com/docs/flags/vercel flags/dashboard/sdk keys)). Activating Vercel Flags creates a FLAGS SECRET per environment for Flags Explorer. For user targeting, attribute types, custom adapter configuration, sharing a @vercel/flags core client, and the Flags Explorer endpoint, see [references/providers.md — Vercel](references/providers.md vercel). Changing what a flag serves (enable, set, split, rollout, rules, archive) happens in the dashboard or with vercel flags , not in code. The vercel flags skill covers those flows; vercel flags <cmd help lists the options. Declaring flags When using Vercel Flags, declare flags with vercelAdapter as shown in [Create a flag]( create a flag). For other providers, see [references/providers.md](references/providers.md). Below are the general flag() patterns. Basic flag Flag with evaluation context Use identify to establish who the request is for. The returned entities are passed to decide : With vercelAdapter , the entity and attribute names in the returned object ( user.id here) are what dashboard rules and vercel flags split rollout rules by target. They must match the entities and attribute types configured in the dashboard. See [references/providers.md — User targeting](references/providers.md user targeting) and [Attribute types](references/providers.md attribute types). Flag with another adapter Adapters connect flags to third party providers. Each adapter replaces decide and origin : See [references/providers.md](references/providers.md) for all supported adapters. Key parameters Parameter Type Description key string Unique flag identifier decide function Resolves the flag value defaultValue any Fallback if decide returns undefined or throws descriptio