Reference

The Flags Explorer has five main concepts: the API Endpoint, the FLAGS_SECRET environment variable, the override cookie, flag definitions, and flag values.

The Flags Explorer needs to know about your feature flags before it can display them.

Flag definitions are metadata for your feature flags, which communicate:

• Name
• URL for where your team can manage the flag
• Description
• Possible values and their (optional) labels

A definition can never communicate the value of a flag as they load independently from flag values. See flag definitions for more information.

This is how Vercel Toolbar shows flag definitions:

There are two ways to provide your feature flags to the Flags Explorer:

1. Returning definitions through the Flags API Endpoint
2. Embedding definitions through script tags

The Flags API Endpoint is the recommended way to provide your feature flags to the Flags Explorer. The Flags Explorer will request your application's Flags API Endpoint to fetch the feature flag definitions and other settings.

See Definitions properties for a full list of properties you can return from your Flags API Endpoint.

We strongly recommend communicating your feature flag definitions through the Flags API Endpoint. In rare cases, it can be useful to communicate feature flag definitions through the HTML response. Vercel Toolbar will pick up any script tags included in the DOM which have a attribute.

If you are using React or Next.js, use the component. If you are using another framework or no framework at all you can render these script tags manually. The expected shape is:

This example shows how to communicate a feature flag definition through the DOM:

You can also encrypt the definitions before emitting them to prevent leaking your feature flags through the DOM.

Your Flags API Endpoint returns your application's feature flag definitions containing information like their key, description, origin, and available options. However the Flags API Endpoint can not return the value a flag evaluated to, since this value might depend on the request which rendered the page initially.

You can optionally provide the values of your feature flags to Flags Explorer in two ways:

1. Emitting values using the React components
2. Embedding values through script tags

Emitted values will show up in the Flags Explorer, and will be used by Web Analytics to annotate events.

This is how Vercel Toolbar shows flag values:

Any JSON-serializable values are supported. Flags Explorer combines these values with any definitions, if they are present.

The package exposes React components which allow making the Flags Explorer aware of your feature flag's values.

The approaches above will add the names and values of your feature flags to the DOM in plain text. Use the function to keep your feature flags confidential.

The component will emit a script tag with a attribute, which get picked up by the Flags Explorer. Flags Explorer 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 manually as shown in the next section.

Flags Explorer scans the DOM for script tags with the attribute. Any changes to content get detected by a mutation observer.

You can emit the values of feature flags to the Flags Explorer by rendering script tags with the attribute.

The expected shape is:

To prevent disclosing feature flag names and values to the client, the information can be encrypted. This keeps the feature flags confidential. Use the Flags SDK's function together with the environment variable to encrypt your flag values on the server before rendering them on the client. The Flags Explorer will then read these encrypted values and use the from your project to decrypt them.

This secret gates access to the Flags API endpoint, and optionally enables signing and encrypting feature flag overrides set by Vercel Toolbar. As described below, you can ensure that the request is authenticated in your Flags API endpoint, by using .

You can create this secret by following the instructions in the Flags Explorer Quickstart. Alternatively, you can create the manually by following the instructions below. If using microfrontends, you should use the same as the other projects in the microfrontends group.

Manually creating the

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:

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

When you have set the environment variable in your project, Flags Explorer will request your application's Flags API endpoint. This endpoint should return a configuration for the Flags Explorer that includes the flag definitions.

Your endpoint should call to ensure the request to load flags originates from Vercel Toolbar. This prevents your feature flag definitions from being exposed publicly thorugh the API endpoint. The header sent by Vercel Toolbar contains proof that whoever made this request has access to . The secret itself is not sent over the network.

If the check fails, you should return status code and no response body. When the check is successful, return the feature flag definitions and other configuration as JSON:

Using the Flags SDK

Using a custom setup

If you are not using the Flags SDK to define feature flags in code, or if you are not using Next.js or SvelteKit, you need to manually return the feature flag definitions from your API endpoint.

The JSON response must have the following shape

These are your application's feature flags. You can return the following data for each definition:

You can optionally tell Vercel Toolbar about the actual value flags resolved to. The Flags API Endpoint cannot return this as the value might differ for each request. See Flag values instead.

In some cases you might need to fetch your feature flag definitions from your feature flag provider before you can return them from the Flags API Endpoint.

In case this request fails you can use . Any hints returned will show up in the UI.

This is useful when you are fetching your feature flags from multiple sources. In case one request fails you might still want to show the remaining flags on a best effort basis, while also displaying a hint that fetching a specific source failed. You can return and simultaneously to do so.

When you create an override, Vercel Toolbar will set a cookie called . You can read this cookie in your applications to make your application respect the overrides set by Vercel Toolbar.

The setting controls the value of the cookie:

• : The cookie will contain the overrides as plain JSON. Be careful not to trust those overrides as users can manipulate the value easily.
• : Vercel Toolbar will encrypt overrides using the before storing them in the cookie. This prevents manipulation, but requries decrypting them on your end before usage.

We highly recommend using mode as it protects against manipulation.

The Flags Explorer will set a cookie called containing the overrides.

Using the Flags SDK

If you use the Flags SDK for Next.js or SvelteKit, the SDK will automatically handle the overrides set by the Flags Explorer.

Manual setup

Read this cookie and use the function to decrypt the overrides and use them in your application. The decrypted value is a JSON object containing the name and override value of each overridden flag.

Vercel Toolbar uses a MutationObserver to find all script tags with and attributes. Any changes to content get detected by the toolbar.

For more information, see the following sections:

• Embedding definitions through script tags
• Embedding values through script tags