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

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.

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.

const values = await unstable_evaluate(precomputeFlags, context);

Description: Evaluates multiple feature flags and returns their values.

const values = await unstable_evaluate(precomputeFlags, context);

Description: Turns evaluated feature flags into their serialized representation.

const values = await unstable_precompute(precomputeFlags, context);
const code = await unstable_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.

const precomputeFlags = [
  showSummerBannerFlag,
  showFreeDeliveryBannerFlag,
  countryFlag,
];
 
const code = await unstable_precompute(precomputeFlags);
 
const [showSummerBanner, showFreeDeliveryBanner] =
  await unstable_getPrecomputed(
    [showSummerBannerFlag, showFreeDeliveryBannerFlag],
    precomputeFlags,
    code,
  );

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

const showSummerSale = unstable_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
const context = { plan: 'pro' };
await unstable_precompute(flags, context);
 
// flags.ts
const plan = unstable_flag({
  key: 'plan',
  decide: () => {
    // this function now has access to the context supplied earlier
    const context = unstable_getPrecomputationContext();
    return context.plan;
  },
});

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

Example usage in generateStaticParams:

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