Using the Flags SDK with Vercel Flags

The Flags SDK is the recommended way to use Vercel Flags in Next.js and SvelteKit applications. It provides a framework-native experience with full TypeScript support and automatic integration with Flags Explorer.

The Getting Started guide covers installing packages, pulling environment variables, defining a flag, and evaluating it in a component. This page builds on that and goes deeper into the adapter, Flags Explorer, targeting, and SvelteKit.

The @flags-sdk/vercel package provides the adapter that connects the Flags SDK to your Vercel Flags project. The Getting Started guide uses vercelAdapter(), which reads the FLAGS environment variable automatically and initializes lazily on first evaluation.

If you need to connect to a different SDK Key — for example, when working with multiple Vercel Flags projects — use createVercelAdapter instead. See SDK Keys for details.

You can declare the possible values a flag can evaluate to using the options array. This works for booleans, strings, numbers, or any other type:

import { flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';
 
export const pricingTier = flag({
  key: 'pricing-tier',
  adapter: vercelAdapter(),
  options: [
    { value: 'standard', label: 'Standard' },
    { value: 'premium', label: 'Premium' },
    { value: 'enterprise', label: 'Enterprise' },
  ],
  description: 'Which pricing tier to show',
});

Declaring options serves these purposes:

• Flags Explorer displays them as a dropdown, so you can override the flag to any declared value during development.
• When Vercel detects the flag as a draft, the options pre-fill the flag configuration when you promote it to a fully managed Vercel Flag.
• When you use the Flags SDK's precompute function the declared options are serialized more efficiently.

The Flags SDK automatically integrates with Flags Explorer, allowing you to view and override flags during development.

To enable this, create a discovery endpoint that exposes your flag definitions:

import { createFlagsDiscoveryEndpoint } from 'flags/next';
import { getProviderData } from '@flags-sdk/vercel';
import * as flags from '../../../../flags';
 
export const GET = createFlagsDiscoveryEndpoint(async (request) => {
  return getProviderData(flags);
});

getProviderData reads the metadata from your flag definitions — keys, descriptions, and options — and returns it in the format Flags Explorer expects.

To evaluate targeting rules based on user attributes, provide an identify function on your flags. This function returns the context that Vercel Flags uses to match targeting rules configured in the dashboard.

import { flag, dedupe } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';
 
type Entities = {
  user?: { id: string; email: string; plan: string };
  team?: { id: string };
};
 
const identify = dedupe(async (): Promise<Entities> => {
  const session = await getSession(); // getSession would be implemented by your app
  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(),
  identify,
});

The dedupe wrapper ensures the context is only computed once per request, even if multiple flags call the same identify function.

For SvelteKit applications, use flags/sveltekit instead of flags/next:

import { flag } from 'flags/sveltekit';
import { vercelAdapter } from '@flags-sdk/vercel';
 
export const showNewFeature = flag({
  key: 'show-new-feature',
  adapter: vercelAdapter(),
});

See the Flags SDK SvelteKit guide for complete setup instructions.

• Set up Flags Explorer for flag overrides during development
• Configure targeting rules in the Vercel Dashboard
• Learn about entities for advanced targeting