Vercel Flags Lab

cd apps/experiments/vercel-flags-lab
pnpm install
pnpm dev

The Vercel Flags Lab covers platform-native Vercel Flags: define flags in the dashboard (or as code drafts), evaluate them with the Flags SDK / @vercel/flags-core, and target using entities such as user.plan. Pair it with the Global Config Lab when you need ultra-low-latency config reads alongside flags.

FeaturesCopy Anchor Link

• Flags SDK definition. flags.ts exports marketingBanner with vercelAdapter() so drafts can surface in the dashboard.
• Local targeting simulator. Sticky FNV bucket + plan rules (enterprise / beta) run entirely in the browser via evaluateLocalFlag.
• Live evaluation. POST /api/flags/evaluate calls flagsClient.evaluate from @vercel/flags-core.
• Honest setup errors. Missing OIDC or missing dashboard flag returns 503 with requirements.

UI ReferenceCopy Anchor Link

Local mode never calls /api - the sticky simulator is pure client TypeScript.

API ReferenceCopy Anchor Link

POST /api/flags/evaluateCopy Anchor Link

Live Flags evaluation only. Local simulation stays in the UI.

curl -X POST http://localhost:3010/api/flags/evaluate \
  -H 'content-type: application/json' \
  -d '{"key":"marketing-banner","userId":"user-7f3a","plan":"enterprise"}'

Implementation DetailsCopy Anchor Link

Code-defined flag:

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

export const marketingBanner = flag({
  key: 'marketing-banner',
  adapter: vercelAdapter(),
  defaultValue: false,
});

Live evaluation path:

const { flagsClient } = await import('@vercel/flags-core');
const result = await flagsClient.evaluate<boolean>(key, false, entities);

evaluateLocalFlag in logic.ts mirrors sticky rollout and plan overrides without calling the network.

Use CasesCopy Anchor Link

• Release features behind dashboard toggles without redeploying
• Target enterprise / beta cohorts with entity attributes
• Progressive percentage rollouts with sticky user assignment

LimitationsCopy Anchor Link

• Live mode needs a flag in the Vercel project Flags UI and OIDC locally.
• Local simulator is not the production evaluation engine - rules you configure in the dashboard are authoritative for live mode.
• Embedded definitions and Flags Explorer behaviour appear after a real Vercel deploy.

Use in your projectCopy Anchor Link

1. Create a flag in the dashboard (or deploy a flag({...}) draft)
2. pnpm add flags @flags-sdk/vercel (and/or @vercel/flags-core)
3. Evaluate in Server Components with await myFlag() or flagsClient.evaluate

DeploymentCopy Anchor Link

Deploy on Vercel

After deploy, create marketing-banner under Flags, toggle environments, and hit Evaluate via Vercel Flags in the demo.

Local DevelopmentCopy Anchor Link

cd apps/experiments/vercel-flags-lab
pnpm install
vercel link && vercel env pull
pnpm dev

Unit tests:

pnpm vitest run ../experiments/vercel-flags-lab

ConfigurationCopy Anchor Link

Vercel / Next.js Features UsedCopy Anchor Link

• Vercel Flags
• Flags SDK (flags/next) + @flags-sdk/vercel
• @vercel/flags-core evaluation engine
• Next.js Route Handlers and Server Components patterns

Next StepsCopy Anchor Link