Feature Flags
Within the utils package, we expose a set of utility functions that allow consumers to use flags to enable or disable features within their application with minimal configuration.
The utils rely on the official @vercel/flags package (only stable parts of it), extending its functionality to cover:
- Integration with the Vercel toolbar (enabling easy overrides of flag values on preview deployments)
- Integration with the edge config store to switch flags on and off without re-deployment
- Encrypted flag values by default (no leakage in the DOM), but comes with an option to be disabled to make flags available on the client (see explanation below)
- A utility to fetch flag values within
getServerSidePropsandmiddleware.ts - A utility to fetch flag values on the client (unencrypted flags only!)
- Optionally 100% type-safe flags with the help of a script that fetches the flags from the edge config store and generates types based on them
Why can't I use encrypted flags on the client?
The package uses a private environment variable to encrypt and decrypt the cookies used to store flag values and overrides.
Since this variable is not available on the client, flags will have to be stored in clear text. If you need to use your flags on the client and this is an acceptable tradeoff for you, you can set encryptionMode to false on every function this packages exposes.
Note: If you disable encryption somewhere along the chain, you'll
need to disable it everywhere, otherwise you will encounter errors.
Setup
Preparation
- Create a new edge config store with an object
flagsin it. Each flag must contain adefaultValueand anoptionsarray. The other fields are optional.
{
"flags": {
"exampleFlag": {
"description": "I am a boolean example",
"origin": "/accounts",
"defaultValue": true,
"options": [
{
"value": true
},
{
"value": false
}
]
},
"anotherFlag": {
"description": "I am a numerical example",
"origin": "/accounts",
"defaultValue": 1,
"options": [
{
"value": 1
},
{
"value": 2
}
]
},
"thirdFlag": {
"description": "I am a string example",
"origin": "/accounts",
"defaultValue": "test1",
"options": [
{
"value": "test1"
},
{
"value": "test2"
}
]
}
}
}
- Make sure you do have the
EDGE_CONFIGenvironment variable that was generated by Vercel available in your local environment. - Generate the flags secret and store it in an environment variable
FLAGS_SECRET(this is used by the package to encrypt your flags cookies)
node -e "console.log(crypto.randomBytes(32).toString('base64url'))"
Integration with your codebase
You are now ready to consume flags wherever you need them.
0. (Optional) Generate types
You can use the provided script to generate a d.ts file containing your flag values. It declares an interface FeatureFlagsType.
The utility functions getFlags and getFlagsOnClient (see usage below) accept a generic object to type them like so: getFlags<FeatureFlagsType>({...})
Install the necessary script runner as dev dependency
pnpm install tsx -D
package.json:
"scripts": {
...
// Make sure to specify the --dir param!
"generate-featureflags-declaration-file": "generate-featureflags-declaration-file --dir='src/types'"
},
1. Attach the flag values as cookie to request via middleware.ts
In order to consume your flags, you need to make them available to your application via a cookie. Therefore, the package exposes a middleware util for you to wrap you res in like so:
import { setFeatureFlagCookie } from '@krakentech/blueprint-utils/feature-flags';
export async function middleware(req: NextRequest) {
const res = NextResponse;
//...you might do some more stuff to some requests here
return setFeatureFlagCookie({
res,
encryptionMode: false, // is true by default, ONLY disable of you need to consume the flags on the client
});
}
If you don't want to wrap all of your requests with the flags cookie, make sure you wrap at least those, which you need to consume from.
Example: If you want to consume the flags on /dashboard/subpage, make sure you wrap the request for it in the middleware
2. a) Usage on the Server
getServerSideProps
import { getFlags } from '@krakentech/blueprint-utils/feature-flags';
const Page = ({ flags }: { flags?: FeatureFlagsType }) => {
return (
<Stack gap="lg" direction="vertical">
{flags?.exampleFlag && (
<div>
OMG FEATURE FLAGS!!!111 🤯🤯🤯 (Set exampleFlag to false to
hide me)
</div>
)}
{flags?.anotherFlag === 1 && (
<div>ANOTHER FLAG HERE (Set anotherFlag to 2 to hide me)</div>
)}
<div></div>
</Stack>
);
};
export const getServerSideProps: GetServerSideProps = async (context) => {
const flags = await getFlags<FeatureFlagsType>({
req: context.req,
encryptionMode: true, // is true by default, ONLY disable of you need to consume the flags on the client
});
return {
props: {
flags: flags,
},
};
};
middleware.ts
import { getFlags } from '@krakentech/blueprint-utils/feature-flags';
export async function middleware(req: NextRequest) {
const flags = getFlags<FeatureFlagsType>({
req,
encryptionMode: true, // is true by default, ONLY disable of you need to consume the flags on the client
});
// consume a flag value and do some re-directing for example
}
3. b) Usage on the Client
import { getFlagsOnClient } from '@krakentech/blueprint-utils/feature-flags';
const Component = ({ flags }: { flags?: FeatureFlagsType }) => {
// be warned, this will throw an error if you are using encrypted flags
const clientSideFlags = getFlagsOnClient<FeatureFlagsType>();
return (
<Stack gap="lg" direction="vertical">
{clientSideFlags?.exampleFlag && (
<div>
OMG FEATURE FLAGS!!!111 🤯🤯🤯 (Set exampleFlag to false to
hide me)
</div>
)}
{clientSideFlags?.anotherFlag === 1 && (
<div>ANOTHER FLAG HERE (Set anotherFlag to 2 to hide me)</div>
)}
<div></div>
</Stack>
);
};
Troubleshooting Errors
You can't use encrypted cookies on the client-> You're trying to usegetFlagsOnClientwhile havingencryptionModeset to true somewhere.Set encryptionMode to true to use encrypted cookies-> You trying to usegetFlagswith encryption turned off while having it set totruein your middlewaresetFeatureFlagCookiefunction.
Note: If you're switching between encrypted and unencrypted flag values during development, you might need to clear out your cookies to avoid these errors.
Integration with the Vercel Toolbar
Currently, you can only change the values of your feature flag directly in the edge config, which kind of defeats the purpose at least for development reasons. What you want is a way to conveniently override flag values but only for you, on your machine. To achieve this, you can install the Vercel toolbar package.
pnpm i @vercel/toolbar
The following steps are very close to the official tutorial, so feel free to reference it for more context.
1. Add the api route
The toolbar interfaces with your flags via an api route, which has to be located here: /pages/api/vercel/flags.ts
import { featureFlagsVercelToolbarHandler } from '@krakentech/blueprint-utils/feature-flags';
import type { NextApiRequest, NextApiResponse } from 'next';
export default async function handler(
request: NextApiRequest,
response: NextApiResponse
) {
await featureFlagsVercelToolbarHandler({
req: request,
res: response,
encryptionMode: true, // is true by default, ONLY disable of you need to consume the flags on the client
});
}
2. Wrap your next.config
To be compatible with the pages router, the toolbar needs a rewrite, since we cant add a route directly to /.well-known
This used to be described in the docs, but has since been removed.
next.config.js
const withVercelToolbar = require('@vercel/toolbar/plugins/next')();
/** @type {import('next').NextConfig} */
const moduleExports = {
// ...your config
async rewrites() {
return [
{
source: '/.well-known/vercel/flags',
destination: '/api/vercel/flags',
},
// ...more of your rewrites
];
},
};
module.exports = withVercelToolbar(moduleExports);
next.config.mjs
import { withVercelToolbar } from '@vercel/toolbar/plugins/next';
const nextConfig = {
// ...your config
async rewrites() {
return [
{
source: '/.well-known/vercel/flags',
destination: '/api/vercel/flags',
},
// ...more of your rewrites
];
},
};
export default withVercelToolbar()(
nextConfig, {
...
});
3. Add the toolbar to your local environment
_app.ts
import { VercelToolbar } from '@vercel/toolbar/next';
import type { AppProps } from 'next/app';
export default function MyApp({ Component, pageProps }: AppProps) {
const shouldInjectToolbar = process.env.NODE_ENV === 'development';
return (
<>
<Component {...pageProps} />
{shouldInjectToolbar && <VercelToolbar />}
</>
);
}
Make sure you also enable the toolbar for preview deployments in your Vercel settings!
4. Expose the current flag values to the toolbar on a given pageProps
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. This is technically optional, but without this component, the toolbar won't show you in which state the flags currently are.
import { getFlags } from '@krakentech/blueprint-utils/feature-flags';
import { FlagValues } from '@vercel/flags/react';
const Page = ({ flags, encryptedFlagValues }: { flags?: FeatureFlagsType, encryptedFlagValues: string }) => {
return (
{flags && <FlagValues values={encryptedFlagValues} />}
<Stack gap="lg" direction="vertical">
{flags?.exampleFlag && (
<div>
OMG FEATURE FLAGS!!!111 🤯🤯🤯 (Set exampleFlag to false to
hide me)
</div>
)}
{flags?.anotherFlag === 1 && (
<div>ANOTHER FLAG HERE (Set anotherFlag to 2 to hide me)</div>
)}
<div></div>
</Stack>
);
};
export const getServerSideProps: GetServerSideProps = async (context) => {
const flags = await getFlags<FeatureFlagsType>({
req: context.req,
encryptionMode: true, // is true by default, ONLY disable of you need to consume the flags on the client
});
// if you're not using encryption, you can simply pass the flags directly to <FlagValues/>
const encryptedFlagValues = await encrypt<FlagValuesType>(flags);
return {
props: {
flags: flags,
encryptedFlagValues: encryptedFlagValues
},
};
};
That's it! You're good to go!
Advanced configuration
If your feature-flags are stored using a custom key or split into multiple objects, we've got you covered!
Let's say you need to split yous config in two:
- the first part is stored using the default
flagskey of your EdgeConfig store, and needs to be encrypted to ensure the data cannot be tampered, - the second part is stored using the
configkey of your EdgeConfig store, and needs to be unencrypted for global access including on static pages.
{
"flags": {
"newDashboardEnabled": {
"description": "Control access to the new dashboard",
"origin": "/dashboard",
"defaultValue": false,
"options": [
{
"value": true
},
{
"value": false
}
]
}
},
"config": {
"companyDisplayName": {
"description": "The display name of the company",
"defaultValue": "Octopus Energy",
"options": [
{
"value": "Octopus Energy"
},
{
"value": "ACME"
}
]
}
}
}
Script
The generate-featureflags-declaration-file script accepts a --key flag, as well as a --type flag to specify a custom type name.
In fact, you can even use as many pairs of EdgeConfig store key and type as you need.
generate-featureflags-declaration-file --dir src/types --key flags --type FeatureFlags --key config --type AppConfig
This will generate a src/types/feature-flags.d.ts
type AllowedValues<T> = {
[P in keyof T]: T[P][number];
};
const schema = {
flags: {
newDashboardEnabled: [true, false],
},
config: {
companyDisplayName: ['Octopus Energy', 'ACME'],
},
} as const;
type Schema = typeof schema;
declare interface FeatureFlags extends AllowedValues<Schema['flags']> {}
declare interface AppConfig extends AllowedValues<Schema['config']> {}
The examples below assume this script was used to generate the type declarations.
Utilities
featureFlagsVercelToolbarHandler
Multiple EdgeConfig store keys can be passed to the Vercel toolbar handler using the edgeConfigStoreKeys option.
Flags from both EdgeConfig store keys will be available and editable in the Vercel toolbar.
await featureFlagsVercelToolbarHandler({
req,
res,
encryptionMode: false,
edgeConfigStoreKeys: ['flags', 'config'],
});
Note: the Vercel toolbar sets a single cookie for all overrides, so if one of your store needs to be accessible client-side you need to set encryptionMode to false.
This is generally not an issue since the Vercel toolbar should only be available locally or in preview enviroment for authenticated Vercel users.
setFeatureFlagCookie
In your middleware.ts file, you can call setFeatureFlagCookie multiple times using different edgeConfigStoreKey and cookieName options.
If the edgeConfigStoreKey and cookieName options are not set the default values are used.
Note: these multiple calls can be made in parallel to reduce latency.
await Promise.all([
setFeatureFlagCookie({
res,
encryptionMode: true,
// edgeConfigStoreKey: 'flags',
// cookieName: 'feature-flags',
}),
setFeatureFlagCookie({
res,
encryptionMode: false,
edgeConfigStoreKey: 'config',
cookieName: 'app-config',
}),
]);
getFlags
Similarly, getFlags also accepts optional edgeConfigStoreKey and cookieName options.
const flags = await getFlags<FeatureFlags>({
req: context.req,
encryptionMode: true,
// edgeConfigStoreKey: 'flags',
// cookieName: 'feature-flags',
});
const appConfig = await getFlags<AppConfig>({
req: context.req,
encryptionMode: false,
edgeConfigStoreKey: 'config',
cookieName: 'app-config',
});
getFlagsOnClient
Finally, getFlagsOnClient also accepts optional edgeConfigStoreKey and cookieName options.
const appConfig = getFlagsOnClient<AppConfig>({
edgeConfigStoreKey: 'config',
cookieName: 'app-config',
});