flags/next | Flags SDK

`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.

Parameter	Type	Description
`key`	`string`	Key of the feature flag.
`decide`	`function`	Resolves the value of the feature flag.
`defaultValue` (Optional)	`any`	Fallback value in case the `decide` function returns `undefined` or throws an error.
`description` (Optional)	`string`	Description of the feature flag.
`origin` (Optional)	`string`	The 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 the Flags Explorer.
`adapter` (Optional)	`Adapter`	Supply an adapter which will implement the `decide` and `origin` functions.
`identify` (Optional)	`Adapter`	Provide an evaluation context which will be passed to `decide`.

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

flags.ts

import { flag } from '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.

Parameter	Type	Description
`flags`	`Record<string, Flag>`	A record where the values are feature flags. The keys are not used.

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

app/.well-known/vercel/flags/route.ts

import { verifyAccess, type ApiData } from 'flags';
import { getProviderData } from 'flags/next';
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.

Parameter	Type	Description
`flags`	`function[]`	Flags
`code`	`string`	Precomputation code generated by the original `precompute` call.

`evaluate`

Description: Evaluates multiple feature flags and returns their values.

Parameter	Type	Description
`flags`	`function[]`	An array of flags declared using `flag`.

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

`serialize`

Description: Turns evaluated feature flags into their serialized representation.

Parameter	Type	Description
`flags`	`function[]`	Feature Flags to be serialized.
`values`	`unknown[]`	The value each flag declared in `flags` resolved to.
`secret` (Optional)	`string`	The secret used to sign the returned representation.

import {
  precompute as precompute,
  serialize as serialize,
} from '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.

Parameter	Type	Description
`flag`	`function \| function[]`	A flag or an array of flags declared using `flag` whose values should be extracted from the precomputation .
`precomputeFlags`	`function[]`	Flags used when `precompute` was called and created the precomputation code.
`code`	`string`	Precomputation code generated by the original `precompute` call.

 
// in your flags.ts file
import {
  getPrecomputed as getPrecomputed,
  precompute as precompute,
} from 'flags/next';
 
const precomputeFlags = [
  showSummerBannerFlag,
  showFreeDeliveryBannerFlag,
  countryFlag,
];
 
// in your middleware.ts file
const code = await precompute(precomputeFlags);
 
// in your page.tsx file
const [showSummerBanner, showFreeDeliveryBanner] = await getPrecomputed(
  [showSummerBannerFlag, showFreeDeliveryBannerFlag],
  precomputeFlags,
  code,
);

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

flags.ts

import { flag, precompute } from 'flags/next';
 
const showSummerSale = flag<boolean>({
  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>.

Parameter	Type	Description
`flags`	`function[]`	Flags
`code`	`string`	Precomputation code generated by the original `precompute` call.

`generatePermutations`

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

Parameter	Type	Description
`flags`	`function[]`	Flags
`filter` (Optional)	`function`	This function is called with every possible precomputation of the flag's options. Return `true` to keep the option.
`secret` (Optional)	`string`	The secret used to sign the generated code. Defaults to `process.env.FLAGS_SECRET`

Example usage in generateStaticParams:

app/[code]/page.tsx

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