菜单
Flags SDK and Vercel Flags expert guidance. Use when declaring feature flags with flag(), wiring provider adapters (Vercel, Statsig, LaunchDarkly, PostHog, and others), managing flags with the vercel flags CLI, implementing the precompute pattern for static A/B tests, or integrating the Flags Explorer.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/vercel/vercel-plugin --skill flags-sdk命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | flags-sdk |
| description | Flags SDK and Vercel Flags expert guidance. Use when declaring feature flags with flag(), wiring provider adapters (Vercel, Statsig, LaunchDarkly, PostHog, and others), managing flags with the vercel flags CLI, implementing the precompute pattern for static A/B tests, or integrating the Flags Explorer. |
| 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"],"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"],"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."}] |
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.
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();
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.
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).flags4.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 targetingflags< 4.2.0.
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.
Check the project state to adapt commands and decide which steps you can skip:
pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb)? → Adapt all package manager commands accordingly (pnpm add, npm install, yarn add, bun add).flags in package.json? → Skip install (step 1).vercel/ directory exist? → Project is linked, skip vercel link in step 2.env.local contain FLAGS=? → Env vars already pulled, skip step 3flags.ts (or lib/flags.ts, src/flags.ts) exist? → Add to it rather than creating from scratch (step 4)@vercel/toolbar in package.json? → Skip toolbar setup (step 6)app/.well-known/vercel/flags/route.ts exist? → Flags Explorer already set up, skip step 7Install packages (if not already in package.json):
pnpm i flags @flags-sdk/vercel
Register the flag with Vercel: Run vercel flags add <flag-key> --kind boolean --description "<description>".
Prerequisite: The
vercel flagscommands require the Vercel CLI to be installed and authenticated. If the Vercel CLI is not installed, runpnpm i -g vercel. For authentication or linking issues, follow thevercel-cliskill if it's already available. If it isn't, suggest the user install it withnpx skills add vercel/vercel@vercel-cli(don't auto-install it) and rely onvercel <command> --helpin 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.
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.
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,
});
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>;
}
Set up the Vercel Toolbar (if not already present):
pnpm i @vercel/toolbarnext.config.ts with the toolbar plugin<VercelToolbar /> in the root layout
See references/nextjs.md — Toolbar Setup for the full code.Set up Flags Explorer (if not already present): Create app/.well-known/vercel/flags/route.ts — see the Flags Explorer setup section below.
Vercel Flags is Vercel's feature flags platform. You create and manage flags from the Vercel dashboard or the vercel flags CLI, then connect them to your code with the @flags-sdk/vercel adapter. When you create a flag in Vercel, the FLAGS and FLAGS_SECRET environment variables are configured automatically.
To create a flag end-to-end, follow the Agent workflow above.
For the full Vercel provider reference — user targeting, vercel flags CLI subcommands, custom adapter configuration, and Flags Explorer setup — see references/providers.md.
When using Vercel Flags, declare flags with vercelAdapter as shown in the Agent workflow. For other providers, see references/providers.md. Below are the general flag() patterns.
import { flag } from 'flags/next'; // or 'flags/sveltekit'
export const showBanner = flag<boolean>({
key: 'show-banner',
description: 'Show promotional banner',
defaultValue: false,
options: [
{ value: false, label: 'Hide' },
{ value: true, label: 'Show' },
],
decide() { return false; },
});
Use identify to establish who the request is for. The returned entities are passed to decide:
import { dedupe, flag } from 'flags/next';
import type { ReadonlyRequestCookies } from 'flags';
interface Entities {
user?: { id: string };
}
const identify = dedupe(
({ cookies }: { cookies: ReadonlyRequestCookies }): Entities => {
const userId = cookies.get('user-id')?.value;
return { user: userId ? { id: userId } : undefined };
},
);
export const dashboardFlag = flag<boolean, Entities>({
key: 'new-dashboard',
identify,
decide({ entities }) {
if (!entities?.user) return false;
return ['user1', 'user2'].includes(entities.user.id);
},
});
Adapters connect flags to third-party providers. Each adapter replaces decide and origin:
import { flag } from 'flags/next';
import { statsigAdapter } from '@flags-sdk/statsig';
export const myGate = flag({
key: 'my_gate',
adapter: statsigAdapter.featureGate((gate) => gate.value),
identify,
});
See references/providers.md for all supported adapters.
| Parameter | Type | Description |
|---|---|---|
key | string | Unique flag identifier |
decide | function | Resolves the flag value |
defaultValue | any | Fallback if decide returns undefined or throws |
description | string | Shown in Flags Explorer |
origin | string | URL to manage the flag in provider dashboard |
options | { label?: string, value: any }[] | Possible values, used for precompute + Flags Explorer |
adapter | Adapter | Provider adapter implementing decide and origin |
identify | function | Returns evaluation context (entities) for decide |
Wrap shared functions (especially identify) in dedupe to run them once per request:
import { dedupe } from 'flags/next';
const identify = dedupe(({ cookies }) => {
return { user: { id: cookies.get('uid')?.value } };
});
Note: dedupe is not available in Pages Router.
To evaluate multiple flags at once, call evaluate() (from flags/next) instead of awaiting flags one at a time or using Promise.all(). To evaluate a single flag, just call it: await myFlag().
import { evaluate } from 'flags/next';
import { flagA, flagB } from '../flags';
// avoid: each await blocks the next, so the flags resolve sequentially
const a = await flagA();
const b = await flagB();
// avoid: parallel, but each flag is evaluated in isolation
const [a, b] = await Promise.all([flagA(), flagB()]);
// prefer: shares work across the batch
const [a, b] = await evaluate([flagA, flagB]);
evaluate() is faster than both approaches. Awaiting flags one at a time makes total latency the sum of every flag's evaluation instead of the slowest single flag, while Promise.all() runs them in parallel but evaluates each in isolation. evaluate() pre-reads headers, cookies, and overrides once for the whole batch and lets adapters resolve a group in a single call, which reduces the number of parallel promises the runtime manages and leaves less room for the async work to be interrupted by other microtasks.
It accepts either an array (positional results) or an object (keyed results):
const [a, b] = await evaluate([flagA, flagB]);
const { a, b } = await evaluate({ a: flagA, b: flagB });
Outside App Router (Pages Router getServerSideProps/API routes, or routing middleware), pass the request as the second argument: await evaluate([flagA, flagB], request).
evaluate() always evaluates flags at request time. It is not for reading precomputed (static) values — for those, use getPrecomputed (or call the flag with the code, await myFlag(code, flagGroup)).
Adapters can opt into batching by implementing the optional bulkDecide hook. The Vercel adapter (@flags-sdk/vercel) implements it — roughly a 10x reduction in evaluation time when resolving hundreds of flags. See references/providers.md — Custom Adapters for implementing bulkDecide, and references/api.md — evaluate for the full signature.
// app/.well-known/vercel/flags/route.ts
import { createFlagsDiscoveryEndpoint } from 'flags/next';
import { getProviderData } from '@flags-sdk/vercel';
import * as flags from '../../../../flags';
export const GET = createFlagsDiscoveryEndpoint(async () => {
return getProviderData(flags);
});
When using a third-party provider alongside Vercel Flags, combine their data with mergeProviderData. Each provider adapter exports its own getProviderData — see the provider-specific examples in references/providers.md.
// src/hooks.server.ts
import { createHandle } from 'flags/sveltekit';
import { FLAGS_SECRET } from '$env/static/private';
import * as flags from '$lib/flags';
export const handle = createHandle({ secret: FLAGS_SECRET, flags });
Required for precompute and Flags Explorer. Must be 32 random bytes, base64-encoded:
node -e "console.log(crypto.randomBytes(32).toString('base64url'))"
Use a separate FLAGS_SECRET value for each environment (Development, Preview, Production), and mark the Preview and Production values as Sensitive. Run the generator once per environment to produce distinct values, then store each on Vercel:
vercel env add FLAGS_SECRET production --sensitive --value <production-secret>
vercel env add FLAGS_SECRET preview --sensitive --value <preview-secret>
vercel env add FLAGS_SECRET development --value <development-secret>
Then run vc env pull to sync to local.
Use precompute to keep pages static while using feature flags. Middleware evaluates flags and encodes results into the URL via rewrite. The page reads precomputed values instead of re-evaluating.
High-level flow:
precompute(flagGroup) in middleware, get a code string/${code}/original-pathcode: await myFlag(code, flagGroup)For full implementation details, see framework-specific references:
Create an adapter factory that returns an object with origin and decide. For the full pattern (including default adapter and singleton client examples), see references/providers.md.
For keeping flag data confidential in the browser (used by Flags Explorer):
| Function | Purpose |
|---|---|
encryptFlagValues | Encrypt resolved flag values |
decryptFlagValues | Decrypt flag values |
encryptFlagDefinitions | Encrypt flag definitions/metadata |
decryptFlagDefinitions | Decrypt flag definitions |
encryptOverrides | Encrypt toolbar overrides |
decryptOverrides | Decrypt toolbar overrides |
All use FLAGS_SECRET by default. Example:
import { encryptFlagValues } from 'flags';
import { FlagValues } from 'flags/react';
async function ConfidentialFlags({ values }) {
const encrypted = await encryptFlagValues(values);
return <FlagValues values={encrypted} />;
}
import { FlagValues, FlagDefinitions } from 'flags/react';
// Renders script tag with flag values for Flags Explorer
<FlagValues values={{ myFlag: true }} />
// Renders script tag with flag definitions for Flags Explorer
<FlagDefinitions definitions={{ myFlag: { options: [...], description: '...' } }} />
Detailed framework and provider guides are in separate files to keep context lean:
flags, flags/react, flags/next, and flags/sveltekit