Implementing Feature Flags in Vercel Toolbar

This quickstart will teach you how to make Vercel Toolbar aware of your application's feature flags, so you can view them, and have your application respect overrides set by Vercel Toolbar. The ability to view and interact with flags from the toolbar makes working with them more convienient, as you no longer need to sign into your feature flag provider to make one-off changes. From the toolbar you can also quickly open feature flags in a provider or share overrides with team members.

• Set up the Vercel Toolbar for development by following adding the Vercel Toolbar to local and production environments
• You should have the latest version of Vercel CLI installed. To check your version, use vercel --version. To install or update Vercel CLI, use:
  pnpm

  yarn

  npm

  pnpm i -g vercel@latest

• Ensure your local directory links to a Vercel project. You can use vercel link from root of your project to link it to your Vercel account or use:
  Terminal

  vercel link [path-to-directory]

To set up feature flag support you can either:

• Use the in-product onboarding flow: Start your project locally and open Vercel Toolbar. Click the Feature Flags icon () to start the onboarding flow.
• Follow the steps below to set feature flags support up without using the onboarding flow

1. Add the flags package to your project

   To make your application aware of your feature flags, you need to install the @vercel/flags package. This package provides convenience methods, components, and types that allow your application to communicate with Vercel Toolbar:

   pnpm

   yarn

   npm

   pnpm i @vercel/flags

2. Adding a FLAGS_SECRET

   This step happens last in the toolbar's onboarding flow, but we'll do it first here as it simplifies the manual setup.

   This secret gates access to the /.well-known/vercel/flags API endpoint we'll create in the next step. This prevents publicly exposing your feature flags.

   In your project's settings, create an environment variable called FLAGS_SECRET. The value must have a specific length (32 random bytes encoded in base64) to work as an encryption key. You can create one using node:

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

   In your local environment, pull your environment variables with vercel env pull to make them available to your project.

   Adding the environment variable locally is not enough. Vercel Toolbar reads it from your project settings in the Vercel dashboard.

3. Creating the Flags API endpoint

   You can tell Vercel Toolbar about your application's feature flags by adding an API endpoint to your application. Vercel Toolbar will then make an authenticated request to this API endpoint to receive your application's feature flag definitions. This endpoint can communicate the name, origin, description, and available options of your feature flags.

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

   TypeScript

   TypeScriptJavaScript

   import { NextResponse, type NextRequest } from 'next/server';
   import { verifyAccess, type ApiData } from '@vercel/flags';
    
   export async function GET(request: NextRequest) {
     const access = await verifyAccess(request.headers.get('Authorization'));
     if (!access) return NextResponse.json(null, { status: 401 });
    
     return NextResponse.json<ApiData>({
       definitions: {
         newFeature: {
           description: 'Controls whether the new feature is visible',
           origin: 'https://example.com/#new-feature',
           options: [
             { value: false, label: 'Off' },
             { value: true, label: 'On' },
           ],
         },
       },
     });
   }

4. Handling overrides

   You can use Vercel Toolbar to create feature flag overrides once you've set up this API Endpoint. When you create an override Vercel Toolbar will set a cookie containing those overrides. Your application can then read this cookie and respect those overrides. You can optionally check the signature on the overrides cookie to ensure it originated from a trusted source.

   app/getFlags.ts

   TypeScript

   TypeScriptJavaScript

   import { FlagOverridesType, decrypt } from '@vercel/flags';
   import { type NextRequest } from 'next/server';
   import { cookies } from 'next/headers';
    
   async function getFlags(request: NextRequest) {
     const overrideCookie = cookies().get('vercel-flag-overrides')?.value;
     const overrides = overrideCookie
       ? await decrypt<FlagOverridesType>(overrideCookie)
       : {};
    
     const flags = {
       exampleFlag: overrides?.exampleFlag ?? false,
     };
    
     return flags;
   }

5. Emitting flag values

   The @vercel/flags package exposes React components which allow making Vercel Toolbar aware of your feature flag's values.

   app/page.tsx

   TypeScript

   TypeScriptJavaScript

   import { FlagValues } from '@vercel/flags/react';
    
   export function Page() {
     return (
       <div>
         {/* Some other content */}
         <FlagValues values={{ exampleFlag: true }} />
       </div>
     );
   }

   The approaches above will add the names and values of your feature flags to the DOM in plain text. To keep your feature flags confidential, use the encrypt function:

   app/page.tsx

   TypeScript

   TypeScriptJavaScript

   import { encrypt } from '@vercel/flags';
   import { FlagValues, type FlagValuesType } from '@vercel/flags/react';
    
   async function ConfidentialFlagValues({ values }: { values: FlagValuesType }) {
     const encryptedFlagValues = await encrypt(values);
     return <FlagValues values={encryptedFlagValues} />;
   }
    
   export function Page() {
     const values = { exampleFlag: true };
     return (
       <div>
         {/* Some other content */}
         <Suspense fallback={null}>
           <ConfidentialFlagValues values={values} />
         </Suspense>
       </div>
     );
   }

   The FlagValues component will emit a script tag with a data-flag-values attribute, which get picked up by Vercel Toolbar. Vercel Toolbar then combines the flag values with the definitions returned by your API endpoint. If you are not using React or Next.js you can render these script tags:

   import { safeJsonStringify } from '@vercel/flags';
    
   <script type="application/json" data-flag-values>
     ${safeJsonStringify({ exampleFlag: true })}
   </script>;

   Use safeJsonStringify to prevent XSS vulnerabilities, which plain JSON.stringify within script tags is susceptible to.

6. Review

   You should now be able to see your feature flags in Vercel Toolbar. You should also be able to set overrides that your application can respect by reading the vercel-flag-overrides cookie. If you added the FlagValues component, you should be able to see the actual value each flag resolved to while rendering the current page.