@vercel/flags/next Reference

The @vercel/flags/next submodule implements the Feature Flags pattern for Next.js App Router.

To learn more about the Flags pattern and the precomputed Flags pattern:

To install the @vercel/flags package, see Install and use the @vercel/flags package.

Description: Declares a feature flag

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

The key, description, origin, and options appear in Vercel Toolbar.

import { unstable_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' },
  ],
});

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

These APIs are relevant for precomputing feature flags.

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

This call is a shorthand for calling unstable_evaluate and unstable_serialize manually.

Description: Evaluates multiple feature flags and returns their values.

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

Description: Turns evaluated feature flags into their serialized representation.

import {
  unstable_precompute as precompute,
  unstable_serialize as serialize,
} from '@vercel/flags/next';
 
const values = await precompute(precomputeFlags, context);
const code = await serialize(precomputeFlags, values);

Note that unstable_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 unstable_flag. That way this serialization can store the index of the matched option instead of its values, which further shortens the emitted.

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

import {
  unstable_getPrecomputed as getPrecomputed,
  unstable_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 {
  unstable_flag as flag,
  unstable_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);

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 unstable_flag. Returns Record<string, unknown>.

Reads the second context supplied by unstable_precompute(flags, context) or unstable_evaluate(flags, context).

When invoking flags using precompute an optional second argument can be supplied as context. This would typically forward a feature flag client or other information which needs flow from middleware into a feature flag's decide function.

// middleware.ts
// any context, in this example we're forwarding a customer's plan
import {
  unstable_flag as flag,
  unstable_getPrecomputationContext as getPrecomputationContext,
  unstable_precompute as precompute,
} from '@vercel/flags/next';
 
const context = { plan: 'pro' };
await precompute(flags, context);
 
// flags.ts
const plan = flag({
  key: 'plan',
  decide: () => {
    // this function now has access to the context supplied earlier
    const context = getPrecomputationContext();
    return context.plan;
  },
});

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

Example usage in generateStaticParams:

import { unstable_generatePermutations as generatePermutations } from '@vercel/flags/next';
 
export async function generateStaticParams() {
  const codes = await generatePermutations(precomputeFlags);
  return codes.map((code) => ({ code }));
}