How Vercel Flags resolves environments

Vercel Flags lets you configure each feature flag differently depending on where your application runs. A flag can be enabled in Development, disabled in Production, and targeted to specific users in Preview without changing code.

The SDK Key used at runtime determines which Vercel Flags environment is evaluated.

Vercel environments and Vercel Flags environments are related, but not the same.

A Vercel environment is where your application runs. Every Vercel project has three built-in environments:

• Production
• Preview
• Development

You can also create custom Vercel environments, such as Staging or QA.

A flag environment is a configuration context inside Vercel Flags. Vercel Flags has exactly three flag environments:

• Production
• Preview
• Development

Each flag environment stores its own flag values, targeting rules, and fallback behavior. You cannot create additional flag environments.

The SDK Key connects these two concepts. Each SDK Key is scoped to one project and one flag environment. When your application evaluates a flag, the SDK Key determines which flag environment's configuration applies.

An SDK Key authenticates your application with Vercel Flags and selects the flag environment to evaluate.

Projects typically have three SDK Keys:

• A Production SDK Key, which resolves to the Production flag environment
• A Preview SDK Key, which resolves to the Preview flag environment
• A Development SDK Key, which resolves to the Development flag environment

Because the SDK Key determines the flag environment, the same application code can evaluate flags differently depending on which SDK Key is present at runtime.

When you create your first feature flag, Vercel automatically creates one SDK Key per flag environment and stores those keys in a FLAGS environment variable on your project.

By default, each Vercel environment receives the matching SDK Key:

• Production receives the Production SDK Key, so it evaluates the Production flag environment.
• Preview receives the Preview SDK Key, so it evaluates the Preview flag environment.
• Development receives the Development SDK Key, so it evaluates the Development flag environment.

The default Vercel Flags SDK clients read from FLAGS automatically. The name FLAGS is the default convention, but you can store SDK Keys in other environment variables and point a custom SDK client at them.

Use createVercelAdapter when you want to read from a custom environment variable instead of FLAGS:

import { flag } from 'flags/next';
import { createVercelAdapter } from '@flags-sdk/vercel';

const adapter = createVercelAdapter(process.env.MY_CUSTOM_FLAGS_KEY);

export const myFlag = flag({
  key: 'my-flag',
  adapter: adapter(),
});

Custom SDK Key variables are useful when you need to evaluate flags from another project or connect one application to multiple flag environments.

Each flag can have different settings in each flag environment. A flag environment can use:

• A static value: Serves the same value to everyone, such as true or "variant-a".
• Targeting rules: Serves different values based on entities, attributes, segments, or weighted splits.
• Linked configuration: One flag environment reuses the configuration from another flag environment.

For example, a flag can be enabled only during development:

• Production: Off
• Preview: Off
• Development: Enabled

This configuration lets developers test the feature locally while keeping it disabled in preview and production deployments.

Lower flag environments can reuse the configuration from higher flag environments.

The supported linking paths are:

• Development can reuse Preview or Production.
• Preview can reuse Production.
• Production cannot reuse Preview or Development.

Production cannot link to a lower environment. This prevents development or preview changes from affecting production by accident.

When you update the source environment, linked environments automatically use the updated configuration.

Segments are not scoped to a single flag environment. A segment, such as Beta testers or Enterprise customers, is defined once and can be used in targeting rules across Production, Preview, and Development.

The rules that use a segment are still configured per flag environment. For example, the same Beta testers segment can be used in a Production rule and ignored in Development.

Custom Vercel environments, such as Staging or QA, must map to one of the three Vercel Flags environments.

By default, Vercel Custom Environments receive the Preview SDK Key. This means the FLAGS environment variable in a custom Vercel environment points to the Preview flag configuration.

To use a different flag environment for a custom Vercel environment:

1. Go to Flags > SDK Keys in the Vercel Dashboard.
2. Find or create an SDK Key for the flag environment you want to use.
3. Override the FLAGS environment variable in your custom Vercel environment with that SDK Key.
4. Redeploy the custom Vercel environment.

In this way, you configure flags once per flag environment instead of repeating the configuration for every custom Vercel environment.

If you need targeting rules that distinguish between custom Vercel environments, pass the environment name as evaluation context. For example, create an entity for the runtime environment and pass values such as staging or qa during flag evaluation.

When your application evaluates a flag, Vercel Flags resolves the value through this chain:

Vercel environment where the app runs
-> SDK Key from FLAGS or a custom environment variable
-> Flag environment: Production, Preview, or Development
-> Flag configuration: static value, targeting rules, or linked configuration
-> Returned flag value

With the default Flags SDK setup, this happens automatically:

import { flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';

export const myFlag = flag({
  key: 'my-flag',
  adapter: vercelAdapter(), // Reads from FLAGS.
});

You don’t need any additional configuration when you use the default FLAGS variable. The SDK Key stored in FLAGS determines the flag environment, and the flag returns the value configured for that environment.

When you deploy to Vercel, the build process can fetch your latest flag definitions once and bundle them into the deployment. This happens automatically when your project has at least one environment variable containing a Vercel Flags SDK Key.

Embedded definitions help with:

• Build consistency: Every function in the build uses the same snapshot of flag definitions.
• Runtime resilience: If Vercel Flags is temporarily unreachable at runtime, the SDK can fall back to the embedded snapshot instead of returning hardcoded default values.

The embedded snapshot preserves your flag configuration, including targeting rules, segments, and percentages. Because the snapshot comes from build time, users may see slightly outdated values until the service recovers.

You can opt out of embedded definitions by setting this environment variable:

VERCEL_FLAGS_DISABLE_DEFINITION_EMBEDDING=1

Because embedded flag definitions are bundled into the deployment, they count toward the function bundle size limit.

• Feature Flag Configuration
• SDK Keys
• Using the Flags SDK with Vercel Flags
• Using the Core Library
• Deployment Environments