Introduction to Vercel’s Flags SDK
In this blog, we will dig into Vercel’s Flags SDK. We'll explore how it works, highlight its key capabilities, and discuss best practices to get the most out of it.
You'll also understand why you might prefer this tool over other feature flag solutions out there. And, despite its strong integration with Next.js, this SDK isn't limited to just one framework—it's fully compatible with React and SvelteKit. We'll use Next.js for examples, but feel free to follow along with the framework of your choice.
Why should I use it?
You might wonder, "Why should I care about yet another feature flag library?" Unlike some other solutions, Vercel's Flags SDK offers unique, practical features. It offers simplicity, flexibility, and smart patterns to help you manage feature flags quickly and efficiently.
It’s simple
Let's start with a basic example:
app
↳flags.js
import { flag } from 'flags/next';
export const exampleFlag = flag({
key: 'example-flag',
identify() {
return { user: { id: '123' } };
},
decide({ entities }) {
return entities.user.id === '123';
},
});
// page.js
const exampleValue = await exampleFlag();
This might look simple — and it is! — but it showcases some important features. Notice how easily we can define and call our flag without repeatedly passing context or configuration.
Many other SDKs require passing the flag's name and context every single time you check a flag, like this:
const exampleValue = await client.getBooleanValue('exampleFlag', context);
This can become tedious and error-prone, as you might accidentally use different contexts throughout your app. With the Flags SDK, you define everything once upfront, keeping things consistent across your entire application.
By "context", I mean the data needed to evaluate the flag, like user details or environment settings. We'll get into more detail shortly.
It’s flexible
Vercel’s Flags SDK is also flexible. You can integrate it with other popular feature flag providers like LaunchDarkly or Statsig using built-in adapters. And if the provider you want to use isn’t supported yet, you can easily create your own custom adapter.
While we'll use Next.js for demonstration, remember that the SDK works just as well with React or SvelteKit.
Latency solutions
Feature flags require definitions and context evaluations to determine their values — imagine checking conditions like, "Is the user ID equal to 12?" Typically, these evaluations involve fetching necessary information from a server, which can introduce latency.
These evaluations happen through two primary functions: identify and decide. The identify function gathers the context needed for evaluation, and this context is then passed as an argument named entities to the decide function. Let's revisit our earlier example to see this clearly:
app
↳flags.js
import { flag } from 'flags/next';
export const exampleFlag = flag({
key: 'example-flag',
identify() {
// Identify our evaluation context
return { user: { id: '123' } };
},
decide({ entities }) {
// Evaluate or decide our value based on our condition
return entities.user.id === '123';
},
});
You could add a custom evaluation context when reading a feature flag, but it’s not the best practice, and it’s not usually recommended.
Using Edge Config
When loading our flags, normally, these definitions and evaluation contexts get bootstrapped by making a network request and then opening a web socket listening to changes on the server. The problem is that if you do this in Serverless Functions with a short lifespan, you would need to bootstrap the definitions not just once but multiple times, which could cause latency issues.
To handle latency efficiently, especially in short-lived Serverless Functions, you can use Edge Config. Edge Config stores flag definitions at the Edge, allowing super-fast retrieval via Edge Middleware or Serverless Functions, significantly reducing latency.
Cookies
For more complex contexts requiring network requests, avoid doing these requests directly in Edge Middleware or CDNs, as this can drastically increase latency. Edge Middleware and CDNs are fast because they avoid making network requests to the origin server. Depending on the end user’s location, accessing a distant origin can introduce significant latency. For example, a user in Tokyo might need to connect to a server in the US before the page can load.
Instead, a good pattern that the Flags SDK offers us to avoid this is cookies. You could use cookies to store context data. The browser automatically sends cookies with each request in a standard format, providing consistent (no matter if you are in Edge Middleware, App Router or Page Router), low-latency access to evaluation context data:
export const exampleFlag = flag({
// Definition
key: 'example-flag',
// Context
identify({ cookies }) {
// We get the cookie that we need for our context
const userId = cookies.get('user-id')?.value;
return { user: userId ? { id: userId } : undefined };
},
// Evaluation
decide({ entities }) {
return entities?.user?.id === 12;
},
});
You can also encrypt or sign cookies for additional security from the client side.
Dedupe
Dedupe helps you cache function results to prevent redundant evaluations. If multiple flags rely on a common context method, like checking a user's region, Dedupe ensures the method executes only once per runtime, regardless of how many times it's invoked. Additionally, similar to cookies, the Flags SDK standardizes headers, allowing easy access to them. Let's illustrate this with the following example:
app
↳flags.js
import { dedupe, flag } from "flags/next";
// Simulate a fake fetch function
async function fakeFetch(url, options) {
return new Response(JSON.stringify({ region: 'EU' }), { status: 200 });
}
// Simulated function to get the user's region from the request headers.
async function getUserRegion(headers) {
// In a real-world scenario, this might involve calling an external geolocation API.
// So we'll use a fake API to simulate the response.
const response = await fakeFetch('https://api.example.com/get-region', {
method: 'GET',
headers: { 'x-country': headers.get('x-country') || '' }
});
const data = await response.json();
return data;
}
// Wrap the region retrieval function using dedupe so that it runs only once per request.
const identifyRegion = dedupe(
async ({ headers }) => {
return await getUserRegion(headers);
},
);
// Define the feature flag that decides the promotional discount eligibility based on the user's region.
export const promoDiscountFlag = flag({
key: 'promo-discount-flag',
// Use the deduped identify function for evaluation context.
identify: identifyRegion,
decide({ entities }) {
// If the region isn’t determined, disable the flag.
if (!entities?.region) return false;
// Only enable the promotion for users in either 'EU' or 'NA'.
return ['EU', 'NA'].includes(entities.region);
},
});
app
↳plans
↳page.jsx
import { promoDiscountFlag } from '../flags';
export default async function PlansPage() {
const isPromoAvailable = await promoDiscountFlag();
return (
<div className="p-4">
<h1 className="text-2xl font-bold mb-4">Store</h1>
<div className="grid grid-cols-1 md:grid-cols-2 gap-4">
<div className="border rounded-lg p-4">
<h2 className="text-xl font-semibold mb-2">Basic Plan</h2>
<p className="text-gray-600 mb-2">Essential features for everyday use</p>
<p className="text-2xl font-bold">$9.99/month</p>
</div>
<div className="border rounded-lg p-4">
<h2 className="text-xl font-semibold mb-2">Premium Plan</h2>
<p className="text-gray-600 mb-2">Advanced features for power users</p>
{ isPromoAvailable ? (
<div>
<p className="text-sm text-gray-500 line-through">$19.99/month</p>
<p className="text-2xl font-bold text-green-600">$14.99/month</p>
<p className="text-sm text-green-600">Special regional promotion!</p>
</div>
) : (
<p className="text-2xl font-bold">$19.99/month</p>
)}
</div>
</div>
</div>
);
}
Server-side patterns for static pages
You can use feature flags on the client side, but that will lead to unnecessary loaders/skeletons or layout shifts, which are never that great. Of course, it brings benefits, like static rendering.
To maintain static rendering benefits while using server-side flags, the SDK provides a method called precompute.
Precompute
Precompute lets you decide which page version to display based on feature flags and then we can cache that page to statically render it. You can precompute flag combinations in Middleware or Route Handlers:
app
↳flags.js
import { flag } from "flags/next";
export const showNewLayout = flag({
// Definition
key: 'new-layout',
// Context
identify({ cookies }) {
const userId = cookies.get('user-id')?.value;
return { user: userId ? { id: userId } : undefined };
},
// Evaluation
decide({ entities }) {
return entities?.user?.id === '12';
},
});
export const showSilksongBanner = flag({
key: 'silksong-banner',
identify({ cookies }) {
return { user: cookies.get('vessel')?.value ? { id: cookies.get('vessel')?.value } : undefined };
},
decide({ entities }) {
return entities?.user?.id === 'hornet';
},
});
// Export our flags in an array (it can be just one or multiple flags)
export const homePageFlags = [showNewLayout, showSilksongBanner];
Next, inside a middleware (or route handler), we will precompute these flags and create static pages per each combination of them.
// middleware.ts
import { type NextRequest, NextResponse } from 'next/server';
import { precompute } from 'flags/next';
import { homePageFlags } from './flags';
// Note that we're running this middleware for / only, but
//You could extend it to further pages you're experimenting on
export const config = { matcher: ['/'] };
export async function middleware(request: NextRequest) {
// precompute returns a string encoding each flag's returned value
const code = await precompute(homePageFlags);
// rewrites the request to include the precomputed code for this flag combination
const nextUrl = new URL(
`/${code}${request.nextUrl.pathname}${request.nextUrl.search}`,
request.url,
);
return NextResponse.rewrite(nextUrl, { request });
}
The user will never notice this because, as we use “rewrite”, they will only see the original URL.
Now, on our page, we “invoke” our flags, sending the code from the params:
app
↳[code]
↳page.jsx
import { Params } from "next/dist/server/request/params";
import { showSilksongBanner, homePageFlags, showNewLayout } from "../flags";
export default async function Page({ params }) {
const { code } = params;
const shouldShowSilksongBanner = await showSilksongBanner(code, homePageFlags);
const shouldShowNewLayout = await showNewLayout(code, homePageFlags);
return (
<div className="p-4">
{shouldShowSilksongBanner && (
<div className="bg-blue-100 p-3 mb-4 rounded">
🎮 Silksong Available
</div>
)}
<div className="bg-white p-4 rounded shadow">
<h1 className="text-xl font-bold mb-2">Welcome to Hallownest</h1>
{shouldShowNewLayout ? (
<div className="mt-4">
<h2 className="font-semibold mb-2">Your Progress</h2>
<div className="space-y-2">
<div>✅ 3 areas completed</div>
<div>🔄 2 areas in progress</div>
<div>🔒 5 areas locked</div>
</div>
</div>
) : (
<p className="text-gray-600">Start your journey in the vast underground kingdom.</p>
)}
</div>
</div>
);
}
By sending our code, we are not really invoking the flag again but getting the value right away. Our middleware is deciding which variation of our pages to display to the user.
Finally, after rendering our page, we can enable Incremental Static Regeneration (ISR). ISR allows us to cache the page and serve it statically for subsequent user requests:
import { Params } from "next/dist/server/request/params";
import { showSilksongBanner, homePageFlags, showNewLayout } from "../flags";
interface HomeParams extends Params {
code: string;
}
export async function generateStaticParams() {
// returning an empty array is enough to enable ISR
return [];
}
export default async function Page({ params }: { params: HomeParams }) {
...
}
Using precompute is particularly beneficial when enabling ISR for pages that depend on flags whose values cannot be determined at build time. Headers, geo, etc., we can’t know their value at build, so we use precompute() so the Edge can evaluate it on the fly. In these cases, we rely on Middleware to dynamically determine the flag values, generate the HTML content once, and then cache it. At build time, we simply create an initial HTML shell.
Generate Permutations
If we prefer to generate static pages at build-time instead of runtime, we can use the generatePermutations function from the Flags SDK. This method enables us to pre-generate static pages with different combinations of flags at build time. It's especially useful when the flag values are known beforehand. For example, scenarios involving A/B testing and a marketing site with a single on/off banner flag are ideal use cases.
app
↳flags.js
import { flag } from 'flags/next';
export const showSilksongBanner = flag({
key: 'showSilksongBanner',
decide() {
return true;
},
});
export const showNewLayout = flag({
key: 'showNewLayout',
decide() {
return true;
},
});
export const greetingStyle = flag({
key: 'greetingStyle',
options: ['classic', 'modern', 'steampunk'],
decide() {
return 'classic';
},
});
export const homePageFlags = [
showSilksongBanner,
showNewLayout,
greetingStyle,
];
import { generatePermutations } from 'flags/next';
import {
showSilksongBanner,
showNewLayout,
greetingStyle,
homePageFlags,
} from '../flags';
import { Params } from 'next/dist/server/request/params';
// 1) at build time, Next will run this and prerender each combo
export async function generateStaticParams() {
const codes = await generatePermutations(homePageFlags);
return codes.map((code) => ({ code }));
}
export default async function Page({ params }) {
const { code } = params;
// 2) at request time, Next simply reads the prerendered HTML for this code
const showBanner = await showSilksongBanner(code, homePageFlags);
const useNewLayout = await showNewLayout(code, homePageFlags);
const style = await greetingStyle(code, homePageFlags);
return (
<div className="p-4">
{showBanner && (
<div className="bg-blue-100 p-3 mb-4 rounded">
🎮 Silksong Available
</div>
)}
<div className="bg-white p-4 rounded shadow">
<h1 className="text-xl font-bold mb-2">
{style === 'steampunk'
? 'Welcome, Cog-and-Gear Explorer!'
: style === 'modern'
? 'Welcome Back to Hallownest'
: 'Welcome to Hallownest'}
</h1>
{useNewLayout ? (
<div className="mt-4">
<h2 className="font-semibold mb-2">Your Progress</h2>
<div className="space-y-2">
<div>✅ 3 areas completed</div>
<div>🔄 2 areas in progress</div>
<div>🔒 5 areas locked</div>
</div>
</div>
) : (
<p className="text-gray-600">
Start your journey in the vast underground kingdom.
</p>
)}
</div>
</div>
);
}
Conclusion
Vercel’s Flags SDK stands out as a powerful yet straightforward solution for managing feature flags efficiently. With its ease of use, remarkable flexibility, and effective patterns for reducing latency, this SDK streamlines the development process and enhances your app’s performance. Whether you're building a Next.js, React, or SvelteKit application, the Flags SDK provides intuitive tools that keep your application consistent, responsive, and maintainable. Give it a try, and see firsthand how it can simplify your feature management workflow!
