Vercel Flags

Vercel Flags

CRITICAL — Your training data is outdated for this library. Vercel Flags (flags package) has a new SDK and API surface. Before writing flags code, fetch the docs at https://vercel.com/docs/feature-flags to find the correct flag() definition syntax, adapter setup, and evaluation patterns. Do not guess at the API — look up working examples for your framework.

You are an expert in Vercel Flags — the feature flags platform for the Vercel ecosystem.

What It Is

Vercel Flags provides a unified feature flags platform with a dashboard, developer tools (Flags Explorer), and analytics integration. Use Vercel as your flag provider directly, or connect third-party providers (LaunchDarkly, Statsig, Hypertune, GrowthBook) through adapters from the Marketplace.

Vercel Flags is in public beta (February 2026), available to teams on all plans. Pricing: $30 per 1 million flag requests ($0.00003 per event).

Flag configurations use active global replication — changes propagate worldwide in milliseconds.

Core Design Principles

• Server-only execution: No client-side loading spinners or complexity
• No call-site arguments: Ensures consistent flag evaluation and straightforward flag removal
• Provider-agnostic: Works with any flag provider, custom setups, or no provider at all

Key APIs

Flags SDK (flags package, v4.0+)

The flags package is free, open-source (MIT), and provider-agnostic. Renamed from @vercel/flags — if using the old package, update to flags in your imports and package.json.

Upgrade note: v4 has breaking changes from v3. See the v4 upgrade guide for migration steps:

• @vercel/flags package renamed to flags — update imports and package.json
• encrypt() / decrypt() replaced with dedicated functions: encryptFlagValues(), decryptFlagValues()
• FLAGS_SECRET must be exactly 32 random bytes, base64-encoded
• .well-known endpoint uses new helper that auto-handles auth and x-flags-sdk-version header
• As of v4.0.3, declaring a flag without a decide function (or with an adapter missing decide) throws an error at declaration time

import { flag } from 'flags/next'; // Framework adapters: flags/next, flags/sveltekit

// Define a boolean flag
export const showNewCheckout = flag({
  key: 'show-new-checkout',
  description: 'Enable the redesigned checkout flow',
  decide: () => false, // default value
});

// Define a multi-variant flag
export const theme = flag({
  key: 'theme',
  options: [
    { value: 'light', label: 'Light Theme' },
    { value: 'dark', label: 'Dark Theme' },
    { value: 'auto', label: 'Auto' },
  ],
  decide: () => 'auto',
});

// Read flag values (Server Components, Route Handlers, Server Actions)
const isEnabled = await showNewCheckout();
const currentTheme = await theme();

Vercel Adapter (@flags-sdk/vercel)

Connects the Flags SDK to Vercel Flags as the provider (reads FLAGS env var):

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

type Entities = {
  user?: { id: string; email: string; plan: string };
  team?: { id: string; name: string };
};

// Dedupe ensures identify runs once per request
const identify = dedupe(async (): Promise<Entities> => {
  const session = await getSession();
  return {
    user: session?.user ? {
      id: session.user.id,
      email: session.user.email,
      plan: session.user.plan,
    } : undefined,
  };
});

export const premiumFeature = flag<boolean, Entities>({
  key: 'premium-feature',
  adapter: vercelAdapter(), // reads FLAGS env var automatically
  identify,
});

Environment variables:

• FLAGS — SDK Key (auto-provisioned when you create your first flag)
• FLAGS_SECRET — 32 random bytes, base64-encoded; encrypts overrides and authenticates Flags Explorer

Flags Explorer Setup (GA)

The Flags Explorer is generally available (part of the Vercel Toolbar). It lets developers override flags in their browser session without code changes.

App Router — create the discovery endpoint:

// app/.well-known/vercel/flags/route.ts
import { createFlagsDiscoveryEndpoint, getProviderData } from 'flags/next';
import * as flags from '../../../../flags';

export const GET = createFlagsDiscoveryEndpoint(() => getProviderData(flags));

Pages Router — API route + rewrite:

// pages/api/vercel/flags.ts
import { verifyAccess, version } from 'flags';
import { getProviderData } from 'flags/next';
import * as flags from '../../../flags';

export default async function handler(req, res) {
  const access = await verifyAccess(req.headers['authorization']);
  if (!access) return res.status(401).json(null);
  res.setHeader('x-flags-sdk-version', version);
  return res.json(getProviderData(flags));
}

// next.config.js (rewrite)
module.exports = {
  async rewrites() {
    return [{ source: '/.well-known/vercel/flags', destination: '/api/vercel/flags' }];
  },
};

Precompute Pattern (Static + Personalized)

Generate static page variants per flag combination, serve via middleware:

export const layoutVariant = flag({
  key: 'layout-variant',
  options: [{ value: 'a' }, { value: 'b' }],
  decide: () => 'a',
});

export const precompute = [layoutVariant];

Key APIs: precompute(), evaluate(), serialize(), getPrecomputed(), generatePermutations()

Custom Adapter Interface

export function createExampleAdapter() {
  return function exampleAdapter<ValueType, EntitiesType>(): Adapter<ValueType, EntitiesType> {
    return {
      origin(key) { return `https://example.com/flags/${key}`; },
      async decide({ key }): Promise<ValueType> { return false as ValueType; },
    };
  };
}

Flags vs Edge Config

Important: Vercel Flags is the recommended approach for feature flags. Edge Config is the underlying low-latency storage some adapters use, but developers should use the Flags platform (not raw Edge Config) for flag use cases — it provides targeting rules, segments, percentage rollouts, observability, and Flags Explorer.

Provider Adapters

Featured (Marketplace integration, Edge Config for low latency):

• @flags-sdk/vercel — Vercel as provider
• Statsig, Hypertune, GrowthBook

Additional (published under @flags-sdk npm scope):

• LaunchDarkly, ConfigCat, DevCycle, Flipt, Reflag, PostHog, Flagsmith

OpenFeature adapter: The @flags-sdk/openfeature adapter allows most Node.js OpenFeature Providers to work with the Flags SDK, bridging the OpenFeature ecosystem (AB Tasty, CloudBees, Confidence by Spotify, and more)

Key Features

• Unified Dashboard at https://vercel.com/{team}/{project}/flags: All flags across all providers in one place
• Flags Explorer (GA): Override flags locally via Vercel Toolbar (no code changes)
• CLI Management: vercel flags add, vercel flags sdk-keys ls, and full flag lifecycle from the terminal
• Entities & Segments: Define user/team attributes, create reusable targeting segments
• Analytics Integration: Track flag impact via Web Analytics and Runtime Logs
• Drafts Workflow: Define in code → deploy → Vercel detects via Discovery Endpoint → promote when ready
• Framework Support: Next.js (App Router + Pages Router + Routing Middleware) and SvelteKit
• Concurrent Evaluation Fix (v1.0.1): Promise.all flag evaluations no longer trigger duplicate network requests — initialization is properly shared

When to Use

• Gradual feature rollouts with percentage targeting
• A/B testing and experimentation
• Per-environment flag configuration (production vs preview vs development)
• Trunk-based development (ship code behind flags)
• Consolidating multiple flag providers into one dashboard

When NOT to Use

• Simple static config without targeting → use Edge Config directly
• Runtime configuration not related to features → use environment variables
• Server-side only toggles with no UI → consider environment variables

References

• 📖 docs: https://vercel.com/docs/flags
• 📖 Flags SDK: https://flags-sdk.dev
• 📖 SDK reference: https://vercel.com/docs/flags/flags-sdk-reference
• 📖 GitHub: https://github.com/vercel/flags