Flags SDK

Quickstart

1. Installation

Install the package using your package manager:

npm install @vercel/flags

2. Usage

Declare a flag and use it on a page

import { flag } from '@vercel/flags/next';
  
// declare a feature flag
const exampleFlag = flag({
  key: "example-flag",
  decide() {
    return true;
  }
});

export default async function Page() {
  // use the feature flag
  const example = await exampleFlag();
  
  return <div>{example ? 'Flag is on' : 'Flag is off'}</div>;
}

That's it! Check your browser and you should see the "Flag is on" text.

Complete your setup

The steps above focus on getting you up and running quickly, so they show the most basic way of using the Flags SDK. Follow the remaining instructions to complete your setup.

Set up the FLAGS_SECRET environment variable

The Flags SDK requires an environment variable called FLAGS_SECRET for features like precomputing and overriding flags.

Its value must be 32 random bytes encoded in base64 to work as an encryption key. Create a secret using node:

node -e "console.log(crypto.randomBytes(32).toString('base64url'))"

Use dedicated files for your feature flags

The steps above defined the feature flag within a page. In Next.js App Router pages can't have arbitrary exports, so we recommend creating one or multiple deciated flags.ts files which export your feature flags.

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

export const exampleFlag = flag({
  key: "example-flag",
  decide() {
    // this flag will be on for 50% of visitors
    return Math.random() > 0.5;
  }
});

Then change your page to import this flag:

import { exampleFlag } from '../flags';

export default async function Page() {
  // use the feature flag
  const example = await exampleFlag();
  
  return <div>{example ? 'Flag is on' : 'Flag is off'}</div>;
}

This way you can import your feature flag into multiple pages.

Integrate the Flags Explorer

The Flags Explorer is a feature of the Vercel Toolbar which allows overriding feature flags for your session only, without affecting your team members. The Flags SDK will automatically respect overrides set by the Flags Explorer.

This is useful when working with feature flags, as you can try out different states without actually changing the feature flag configuration in the flag provider.

Next steps

There is much more to the Flags SDK than shown in this quickstart. Make sure to explore the Concepts to learn how to target individual users, how to use feature flags for static pages, how to integrate feature flag providers using adapters, and much more.