Reference
4 min read

@vercel/flags/next Reference

The reference for the @vercel/flags/next submodule
Table of Contents

The flags pattern and precomputed flags pattern exported from @vercel/flags/next are experimental. We are still actively researching and have further iterations planned. These exports are not covered by semantic versioning as indicated by the unstable_ prefix.

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.

ParameterTypeDescription
keystringKey of the feature flag.
decidefunctionResolves the value of the feature flag.
defaultValue (Optional)anyFallback value in case the decide function returns undefined or throws an error.
description (Optional)stringDescription of the feature flag.
origin (Optional)stringThe URL where this feature flag can be managed.
options (Optional){ label?: string, value: any }[]Possible values a feature flag can resolve to, which are displayed in Vercel Toolbar.

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

flags.ts
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.

ParameterTypeDescription
flagsRecord<string, Flag>A record where the values are feature flags. The keys are not used.

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.

ParameterTypeDescription
flagsfunction[]Flags
codestringPrecomputation code generated by the original precompute call.

Description: Evaluates multiple feature flags and returns their values.

ParameterTypeDescription
flagsfunction[]An array of flags declared using unstable_flag.
context (Optional)anyA value which will be made available through unstable_getPrecomputationContext from within a flag's decide function.
const values = await unstable_evaluate(precomputeFlags, context);

Description: Evaluates multiple feature flags and returns their values.

ParameterTypeDescription
flagsfunction[]An array of flags declared using unstable_flag.
context (Optional)anyA value which will be made available through unstable_getPrecomputationContext from within a flag's decide function.
const values = await unstable_evaluate(precomputeFlags, context);

Description: Turns evaluated feature flags into their serialized representation.

ParameterTypeDescription
flagsfunction[]Feature Flags to be serialized.
valuesunknown[]The value each flag declared in flags resolved to.
secret (Optional)stringThe secret used to sign the returned 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.

ParameterTypeDescription
flagfunction | function[]A flag or an array of flags declared using unstable_flag whose values should be extracted from the precomputation .
precomputeFlagsfunction[]Flags used when precompute was called and created the precomputation code.
codestringPrecomputation code generated by the original precompute call.
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:

flags.ts
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>.

ParameterTypeDescription
flagsfunction[]Flags
codestringPrecomputation code generated by the original precompute call.

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.

ParameterTypeDescription
flagsfunction[]Flags
filter (Optional)functionThis function is called with every possible precomputation of the flag's options. Return true to keep the option.
secret (Optional)stringThe secret used to sign the generated code. Defaults to process.env.FLAGS_SECRET

Example usage in generateStaticParams:

export async function generateStaticParams() {
  const codes = await unstable_generatePermutations(precomputeFlags);
  return codes.map((code) => ({ code }));
}
Last updated on June 21, 2024