The `flags` package provides the core functionality for integrating with Vercel.
verifyAccess
A method for verifying access to your flags endpoint based on encrypted tokens (JWEs) generated by the SDK functions documented below.
You can use verifyAccess to keep your endpoint private, but allow the Vercel Toolbar to access it. Returns a Promise with a true or false value.
If you are using Next.js App Router you should use createFlagsDiscoveryEndpoint instead, which will create the full route handler.
| Parameter | Type | Description |
|---|---|---|
authorization | string | Authorization token to verify |
import { NextResponse, type NextRequest } from "next/server";
import { verifyAccess, version, type ProviderData, type ApiData } from "flags";
export async function GET(request: NextRequest) {
const access = await verifyAccess(request.headers.get('Authorization'));
if (!access) return NextResponse.json(null, { status: 401 });
const providerData: ProviderData = /* ... */
return NextResponse.json<ApiData>(providerData, {
headers: { 'x-flags-sdk-version': version },
});
}If you are using the Pages router, you will need to add the following to your next.config.js. This is because the Pages router can't specify API routes outside of the api folder. This means you need a rewrite.
import type { NextApiRequest, NextApiResponse } from "next";
import { type ProviderData, verifyAccess } from "flags";
export async function handler(request: NextApiRequest, response: NextApiResponse) {
const access = await verifyAccess(request.headers.get('Authorization'));
if (!access) return response.json(null, { status: 401 });
const providerData: ProviderData = { ... };
return response.status(200).json(providerData);
}module.exports = {
async rewrites() {
return [
{
source: '/.well-known/vercel/flags',
destination: '/api/vercel/flags',
},
];
},
};mergeProviderData
Merges provider data from multiple sources. Extends the feature flags defined in code with metadata from your feature flag provider, for use with the Flags Explorer.
| Parameter | Type | Description |
|---|---|---|
data | (ProviderData | Promise<ProviderData>)[] | A list of provider data objects to merge. |
import { getProviderData, createFlagsDiscoveryEndpoint } from 'flags/next';
import { getProviderData as getStatsigProviderData } from '@flags-sdk/statsig';
import { mergeProviderData } from 'flags';
import * as flags from '../../../../flags';
export const GET = createFlagsDiscoveryEndpoint(async (request) => {
return mergeProviderData([
getProviderData(flags),
getStatsigProviderData({
consoleApiKey: process.env.STATSIG_CONSOLE_API_KEY,
projectId: process.env.STATSIG_PROJECT_ID,
}),
]);
});reportValue
Reports the value of a feature flag to Vercel so it can show up in Runtime Logs and be used with Web Analytics custom server-side events. Returns undefined.
| Parameter | Type | Description |
|---|---|---|
key | string | Key of the feature flag |
value | any | Value of the feature flag |
import { reportValue } from 'flags';
reportValue('summer-sale', true);Encryption and Decryption Functions
The flags package provides multiple purpose-specific encryption and decryption functions for different types of flag data. These functions add purpose claims to prevent misuse between different data types.
encryptFlagValues
Encrypts flag values data with a purpose claim. Returns a Promise.
| Parameter | Type | Description |
|---|---|---|
flagValues | FlagValuesType | Flag values to be encrypted |
secret (Optional) | string | The secret being used to encrypt. Defaults to process.env.FLAGS_SECRET |
expirationTime (Optional) | string | number | Date | When the encrypted data should expire. Defaults to '1y' (1 year) |
import { encryptFlagValues, type FlagValuesType } from 'flags';
import { FlagValues } from 'flags/react';
async function ConfidentialFlagValues({ values }: { values: FlagValuesType }) {
const encryptedFlagValues = await encryptFlagValues(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>
);
}decryptFlagValues
Decrypts flag values data, ensuring the proper purpose claim. Returns a Promise.
| Parameter | Type | Description |
|---|---|---|
encryptedData | string | Encrypted flag values to be decrypted |
secret (Optional) | string | The secret being used to decrypt data. Defaults to process.env.FLAGS_SECRET |
encryptFlagDefinitions
Encrypts flag definitions data with a purpose claim. Returns a Promise.
| Parameter | Type | Description |
|---|---|---|
flagDefinitions | FlagDefinitionsType | Flag definitions to be encrypted |
secret (Optional) | string | The secret being used to encrypt. Defaults to process.env.FLAGS_SECRET |
expirationTime (Optional) | string | number | Date | When the encrypted data should expire. Defaults to '1y' (1 year) |
decryptFlagDefinitions
Decrypts flag definitions data, ensuring the proper purpose claim. Returns a Promise.
| Parameter | Type | Description |
|---|---|---|
encryptedData | string | Encrypted flag definitions to be decrypted |
secret (Optional) | string | The secret being used to decrypt data. Defaults to process.env.FLAGS_SECRET |
encryptOverrides
Encrypts flag overrides data with a purpose claim. Returns a Promise.
| Parameter | Type | Description |
|---|---|---|
overrides | FlagOverridesType | Flag overrides to be encrypted |
secret (Optional) | string | The secret being used to encrypt. Defaults to process.env.FLAGS_SECRET |
expirationTime (Optional) | string | number | Date | When the encrypted data should expire. Defaults to '1y' (1 year) |
decryptOverrides
Decrypts flag overrides data, ensuring the proper purpose claim. Returns a Promise.
| Parameter | Type | Description |
|---|---|---|
encryptedData | string | Encrypted flag overrides to be decrypted |
secret (Optional) | string | The secret being used to decrypt data. Defaults to process.env.FLAGS_SECRET |
The primary use case for decryptOverrides is decrypting data stored inside the vercel-flag-overrides cookie.
import { FlagOverridesType, decryptOverrides } from '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 decryptOverrides(overrideCookie)
: {};
const flags = {
exampleFlag: overrides?.exampleFlag ?? false,
};
return flags;
}verifyAccessProof
Compared to verifyAccess which is used commonly to keep your endpoint private, verifyAccessProof may rarely be needed for advanced use cases.
Verifies that an access proof token is valid. Returns a Promise with a true or false value.
| Parameter | Type | Description |
|---|---|---|
encryptedData | string | Encrypted access proof token to verify |
secret (Optional) | string | The secret used for decryption. Defaults to process.env.FLAGS_SECRET |
import { verifyAccessProof } from 'flags';
// Example of verifying an access proof token
const isValid = await verifyAccessProof(tokenFromRequest);
if (isValid) {
// Handle valid token
}safeJsonStringify
A safe version of JSON.stringify that escapes the resulting output to prevent XSS attacks. Returns string.
| Parameter | Type | Description |
|---|---|---|
value | any | A valid JSON object to convert |
replacer (Optional) | function | Array | A replacer function or Array |
space (Optional) | string | number | Specifies the spacing in the output |
import { safeJsonStringify } from 'flags';
safeJsonStringify({ markup: '<html></html>' });
// '{"markup":"\\u003chtml>\\u003c/html>"}'