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 (including vercel env pull when .env.local is missing). When they ask to create or add a flag, follow 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. 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): ``bash pnpm i flags @flags-sdk/vercel ``

1. 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. If the project is not linked, run vercel link.

1. Pull environment variables: If .env.local lacks VERCEL_OIDC_TOKEN=, follow Pull environment variables.

1. 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 for the full code.

1. 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.

1. Set up Flags Explorer (if not already present): Create app/.well-known/vercel/flags/route.ts — see 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) 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). If FLAGS_SECRET is still missing after the pull, generate it per 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. For a CLI-only request, run step 2 only. 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 instead.

Before you start

• Complete 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. Skip this entirely for a CLI-only request.
• Does .env.local contain VERCEL_OIDC_TOKEN=? → Env vars already pulled; see 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 if needed, then continue.

1. Register the flag with Vercel: Run vercel flags create <flag-key> --kind boolean --description "<description>".

Target the project as described in Project targeting.

1. Pull environment variables: If this is the project's first flag, follow Pull environment variables again; activation created the FLAGS_SECRET.

1. Declare the flag in code: Add it to flags.ts (or create the file if it doesn't exist) using vercelAdapter: ```ts import { flag } from 'flags/next'; import { vercelAdapter } from '@flags-sdk/vercel';

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