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.

What It Is

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+)

flags

@vercel/flags

flags

package.json

• @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

)

FLAGS

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,
});

• 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)

// 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/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)

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

export const precompute = [layoutVariant];

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

Provider Adapters

• @flags-sdk/vercel

  — Vercel as provider
• Statsig, Hypertune, GrowthBook

@flags-sdk

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

@flags-sdk/openfeature

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