vercel[bot]
a41fa47627
Audited every path through the function returned by `flag()` for whether
it opts the caller out of the prerender. No `await connection()` turned
out to be necessary:
- App Router (`flagFn()`, and `evaluate()` without a request) awaits
`headers()` and `cookies()` before calling `decide`. Those are
Request-time APIs, so awaiting a flag already has the effect of
`connection()`. Adding it would mean importing `next/server` — which
`flags/next` avoids at the top level to keep working in Pages Router —
and awaiting one more promise per evaluation, with no change in
behavior.
- The per-request evaluation cache is keyed by the sealed headers object,
so a cache read can only be reached after that request-time read. It
needs no `connection()` of its own.
- Pages Router and routing middleware are handed a request by the caller
and are request-scoped by definition. `connection()` is App Router-only.
- Reading a precomputed value and `evaluate([])` deliberately read
nothing from the request. Adding `connection()` there would break the
entire point of precompute, which is keeping pages prerenderable.
Since the guarantee comes from the SDK rather than from any individual
`decide`, it is easy to break by accident, so this locks it in:
- `packages/flags/src/next/dynamic-rendering.test.ts` asserts which paths
read `headers()`/`cookies()` and which must not — including cache hits,
overrides, bulk evaluation, and precomputed reads.
- `tests/next-1{5,6}` gain an `/app-router-dynamic` route rendering a flag
whose `decide` ignores the request and returns a new value every time.
Next 15 reports it as `ƒ (Dynamic)`, Next 16 (Cache Components) streams
it outside the shell, and an e2e test asserts two requests differ. On
Next 16 the build itself is an assertion: without the SDK's request read
it fails with `next-prerender-random`.
Also documents the behavior for users, in the `flags/next` API reference
and the flags-sdk skill, so nobody adds `await connection()` in front of
a flag evaluation.
No runtime change, hence no changeset.
Co-Authored-By: Dominik Ferber <1765075+dferber90@users.noreply.github.com>
Flags SDK
The feature flags toolkit for Next.js and SvelteKit.
From the creators of Next.js, the Flags SDK is a free open-source library that gives you the tools you need to use feature flags in Next.js and SvelteKit applications.
- Works with any flag provider, custom setups or no flag provider at all
- Compatible with App Router, Pages Router, and Routing Middleware
- Built for feature flags and experimentation
See flags-sdk.dev for full docs and examples.
Upgrading from version 3? See the Upgrade to v4 guide.
Installation
Install the package using your package manager:
npm install flags
Setup
Create an environment variable called FLAGS_SECRET.
The FLAGS_SECRET value must have a specific length (32 random bytes encoded in base64) to work as an encryption key. Create one using node:
node -e "console.log(crypto.randomBytes(32).toString('base64url'))"
Use a separate FLAGS_SECRET value for each environment (Development, Preview, Production), and mark the Preview and Production values as Sensitive. Run the generator once per environment to produce distinct values, then store each on Vercel:
vercel env add FLAGS_SECRET production --sensitive --value <production-secret>
vercel env add FLAGS_SECRET preview --sensitive --value <preview-secret>
vercel env add FLAGS_SECRET development --value <development-secret>
This secret is required to use the SDK. It is used to read overrides and to encrypt flag values in case they are sent to the client and should stay secret.
Usage
Create a file called flags.ts in your project and declare your first feature flag there:
// app/flags.tsx
import { flag } from "flags/next";
export const exampleFlag = flag<boolean>({
key: "example-flag",
decide() {
return true;
},
});
Call your feature flag in a React Server Component:
// app/page.tsx
import { exampleFlag } from "./flags";
export default async function Page() {
const example = await exampleFlag();
return <div>{example ? "Flag is on" : "Flag is off"}</div>;
}
Feature Flags can also be called in Routing Middleware and API Routes.
Adapters
The Flags SDK has adapters for popular feature flag providers including LaunchDarkly, Optimizely, and Statsig.
Documentation
There is a lot more to the Flags SDK than shown in the example above.
See the full documentation and examples on flags-sdk.dev.