--- title: How Vercel Flags resolves environments description: Configure Vercel Flags per environment by using environment-scoped SDK Keys that map your Vercel deployment environment to the correct flag environment url: /kb/guide/how-vercel-flags-resolves-environments canonical_url: "https://vercel.com/kb/guide/how-vercel-flags-resolves-environments" last_updated: 2026-06-17 authors: Dominik Ferber related: - /docs/deployments/environments - /docs/flags/vercel-flags/dashboard/feature-flag - /docs/flags/vercel-flags/dashboard/sdk-keys - /docs/flags/vercel-flags/sdks/flags-sdk - /docs/flags/vercel-flags/sdks/core install_vercel_plugin: npx plugins add vercel/vercel-plugin --- 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 vs flag environments [Vercel environments](https://vercel.com/docs/deployments/environments) and [Vercel Flags environments](https://vercel.com/docs/flags/vercel-flags/dashboard/feature-flag#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. ## How SDK Keys select a flag environment 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. > SDK Keys are secrets. Each SDK Key grants read-only access to the full flag configuration for its environment, including data used in targeting rules, such as email addresses. Never expose SDK Keys in client-side code or commit them to version control. ## The `FLAGS` environment variable 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. ## Configure flags per flag environment 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. ## Link flag environments 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 shared across flag environments 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 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. ## Resolution flow 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. ## Build-time embedding 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. ## Next Steps - [Feature Flag Configuration](https://vercel.com/docs/flags/vercel-flags/dashboard/feature-flag) - [SDK Keys](https://vercel.com/docs/flags/vercel-flags/dashboard/sdk-keys) - [Using the Flags SDK with Vercel Flags](https://vercel.com/docs/flags/vercel-flags/sdks/flags-sdk) - [Using the Core Library](https://vercel.com/docs/flags/vercel-flags/sdks/core#embedded-definitions) - [Deployment Environments](https://vercel.com/docs/deployments/environments)