Tutorial
8 min read

Quickstart

Learn how to set up Vercel Toolbar so you can see and override your application's feature flags
Table of Contents

Feature flags are available in Beta on all plans

Before supporting feature flag overrides, familiarise yourself with feature flag concepts.

This quickstart will teach you how to make Vercel Toolbar aware of your application's feature flags, so you can view and override them. 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. 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.

  2. 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, description, and available options of your feature flags.

    Next.js (/app)
    Next.js (/pages)
    app/.well-known/vercel/flags/route.ts
    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' },
            ],
          },
        },
      });
    }
  3. 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.

    Next.js (/app)
    Next.js (/pages)
    app/getFlags.ts
    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;
    }
  4. The @vercel/flags package exposes React componentes which allow making Vercel Toolbar aware of your feature flag's values.

    Next.js (/app)
    Next.js (/pages)
    app/page.tsx
    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:

    Next.js (/app)
    Next.js (/pages)
    app/page.tsx
    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.

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

Last updated on May 18, 2024