Flags SDK

@vercel/flags/next

APIs for working with feature flags in Next.js.

flag

Description: Declares a feature flag

A feature flag declared this way will automatically respect overrides set by the Flags Explorer and integrate with Runtime Logs, Web Analytics, and more.

The key, description, origin, and options appear in the Flags Explorer.

import { flag as flag } from '@vercel/flags/next';

export const showSummerSale = flag<boolean>({
  key: 'summer-sale',
  async decide() {
    return false;
  },
  origin: 'https://example.com/flags/summer-sale/',
  description: 'Show Summer Holiday Sale Banner, 20% off',
  defaultValue: false,
  options: [
    // options are not necessary for boolean flags, but we customize their labels here
    { value: false, label: 'Hide' },
    { value: true, label: 'Show' },
  ],
});

getProviderData

Description: Turns flags declared using flag into Vercel Toolbar compatible definitions.

Use getProviderData to surface the feature flags defined in code to the Flags Explorer using the Flags Explorer API endpoint.

import { verifyAccess, type ApiData } from '@vercel/flags';
import { getProviderData } from '@vercel/flagas';
import { NextResponse, type NextRequest } from 'next/server';
import * as flags from '../../../../flags'; // your feature flags file(s)
 
export async function GET(request: NextRequest) {
  const access = await verifyAccess(request.headers.get('Authorization'));
  if (!access) return NextResponse.json(null, { status: 401 });
 
  const providerData = getProviderData(flags);
 
  return NextResponse.json<ApiData>(providerData);
}

Precomputation

These APIs are relevant for precomputing feature flags.

precompute

Description: Evaluates multiple feature flags. Returns their values encoded to a single signed string.

This call is a shorthand for calling evaluate and serialize manually.

evaluate

Description: Evaluates multiple feature flags and returns their values.

import { evaluate as evaluate } from '@vercel/flags/next';
const values = await evaluate(precomputeFlags);

serialize

Description: Turns evaluated feature flags into their serialized representation.

import {
  precompute as precompute,
  serialize as serialize,
} from '@vercel/flags/next';

const values = await precompute(precomputeFlags, context);
const code = await serialize(precomputeFlags, values);

Note that serialize compresses to a tiny format, with only two bytes per feature flag and a few bytes overhead for JWS signature.

The underlying algorithm basically has special values for boolean values and null. If your feature flag can return non-boolean values, it's advised to declare them in options when declaring the flag using flag. That way this serialization can store the index of the matched option instead of its values, which further shortens the emitted.

getPrecomputed

Description: Retrieves the value of one or multiple feature flags from the precomputation and returns them as an array.

import {
  getPrecomputed as getPrecomputed,
  precompute as precompute,
} from '@vercel/flags/next';

const precomputeFlags = [
  showSummerBannerFlag,
  showFreeDeliveryBannerFlag,
  countryFlag,
];

const code = await precompute(precomputeFlags);

const [showSummerBanner, showFreeDeliveryBanner] = await getPrecomputed(
  [showSummerBannerFlag, showFreeDeliveryBannerFlag],
  precomputeFlags,
  code,
);

It is recommended to call the feature flag directly, for example:

import {
  flag as flag,
  precompute as precompute,
} from '@vercel/flags/next';

const showSummerSale = flag({
  key: 'summer-sale',
  decide: () => false,
});

const precomputeFlags = [
  showSummerSale,
  /*...*/
];

const code = await precompute(precomputeFlags);

// This will not actually invoke `showSummerSale`'s `decide` function, it will just read the result.
const sale = await showSummerSale(code, precomputeFlags);

deserialize

Description: Retrieves the value of all feature flags and returns them as a record. Keys will be the key passed to when declaring flags using flag. Returns Record<string, unknown>.

generatePermutations

Description: Calculates all precomputations of the options of the provided flags.

Example usage in generateStaticParams:

import { generatePermutations as generatePermutations } from '@vercel/flags/next';

export async function generateStaticParams() {
  const codes = await generatePermutations(precomputeFlags);
  return codes.map((code) => ({ code }));
}