How Vercel Flags are evaluated

Vercel Flags lets you control which flag value each user, team, or other entity receives. You can release a feature to your team first, test it in production, and keep the feature off for everyone else until you're ready.

Vercel Flags evaluates a flag by checking the active environment, the supplied evaluation context, direct targets, rules, and fallback outcome.

Vercel Flags evaluates each flag in this order:

1. Environment configuration: Vercel Flags uses the flag configuration for the current environment.
2. Direct targets: If the evaluation context matches a directly targeted entity, Vercel Flags returns the assigned option.
3. Rules: If no direct target matches, Vercel Flags evaluates rules from top to bottom.
4. Fallback outcome: If no rules match, Vercel Flags returns the fallback outcome configured for the flag.

Vercel Flags can use different flag behavior for each environment. Production, preview, and development environments share the same flags, but each environment can have its own targeting, rules, and fallback outcomes.

This lets you enable a flag in development while keeping it disabled in preview and production.

For more information, see Feature Flag Configuration.

Vercel Flags requires an explicit evaluation context. An evaluation context is the data your application passes when evaluating a flag, such as the current user, team, account, or workspace.

Vercel Flags includes default entities for users and teams. You can extend these defaults and configure additional entities in the Entities dashboard.

The entities you configure are used in the flag details UI. The UI adapts to the configured entities and their attributes, so your team can target and display the same context your application passes during evaluation.

Advanced configuration requires an evaluation context when your application evaluates a flag. Vercel Flags uses this context to match direct targets, evaluate rules, and calculate split outcomes.

When using the Flags SDK, provide the evaluation context with an identify function.

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

type Entities = {
  user?: {
    id: string;
    email: string;
    plan: string;
  };
};

const identify = dedupe(async (): Promise<Entities> => {
  const session = await getSession();

  // Provide attributes based on the current user session
  return {
    user: session?.user
      ? {
          id: session.user.id,
          email: session.user.email,
          plan: session.user.plan,
        }
      : undefined,
  };
});

export const premiumFeature = flag<boolean, Entities>({
  key: 'premium-feature',
  adapter: vercelAdapter(),
  identify,
});

The identify function returns the entity attributes that Vercel Flags uses during evaluation.

Vercel Flags evaluates entities fresh for each flag call. If you don't provide an entity or attribute, rules that target that missing data won't match.

For more information, see Using the Flags SDK with Vercel Flags.

Direct targeting is evaluated before rules. If an entity is targeted directly, Vercel Flags does not evaluate any rules for that flag. The flag returns the option assigned to the targeted entity.

You can assign direct targets to specific variants. You can also add an optional note explaining why the target was assigned to that variant. Notes help teammates understand the reason for the assignment.

If no direct target matches, Vercel Flags evaluates rules next. Rules use the entities you configured and the evaluation context your application passed when evaluating the flag.

Rules let you define more detailed targeting logic than direct assignment. Rules can be reordered, but direct targeting always runs before rules.

Rules are evaluated from top to bottom. A rule matches when all of its filters match the evaluation context. Each rule must have at least one filter.

When a rule matches, Vercel Flags returns that rule's outcome and stops evaluating the remaining rules. If no rules match, Vercel Flags returns the fallback outcome configured at the bottom of the flag.

For example, this evaluation context includes a user and team:

{
  "user": {
    "id": "user_123",
    "email": "ava@example.com",
    "plan": "pro"
  },
  "team": {
    "id": "team_789",
    "name": "Acme"
  }
}

Given that context, Vercel Flags evaluates ordered rules like this:

Labels make common entity IDs easier to recognize in the Vercel Flags UI. You can configure labels for common IDs in the Entities dashboard.

After you add a label, Vercel Flags displays the label instead of the raw ID in relevant parts of the UI. Add labels for commonly used IDs so teammates can understand targeting and rules without looking up each ID.

An outcome is the value Vercel Flags returns after a target or rule matches. If no target or rule matches, Vercel Flags returns the fallback outcome.

A fixed outcome serves the same option to every user matched to it. Vercel Flags supports boolean, string, and number flags.

A fixed outcome always returns the same option for every evaluation context that reaches that outcome.

Use a fixed outcome when everyone who reaches that target, rule, or fallback should receive the same value.

A weighted split outcome assigns evaluation contexts to variants based on the attribute you select. For example, if you split by user ID, Vercel Flags uses each user's ID to assign that user to a variant.

Choose an attribute that is unique for the entity being evaluated, such as a user ID or team ID. If the selected attribute is not unique, the split will not distribute evenly.

For example, these two users share the same plan value but have different id values:

[
  {
    "user": {
      "id": "user_123",
      "plan": "pro"
    }
  },
  {
    "user": {
      "id": "user_456",
      "plan": "pro"
    }
  }
]

If the split is based on user.id, these users can land in different buckets. If the split is based on user.plan, both users use the same split input, pro, and land in the same bucket.

If the selected base attribute is not provided in the evaluation context, Vercel Flags returns the fallback value configured for the split.

Weighted split outcomes can be used as the outcome of a rule or as the fallback outcome when no direct targets or rules match.

A progressive rollout outcome moves evaluation contexts from one variant to another over a configured schedule. For example, you can start with Off, roll out On to 10% of users, increase to 25% after one hour, then continue until the rollout reaches 100%.

Gradual rollouts are useful when you want Vercel Flags to increase exposure over time without manually editing the rollout percentage at each step.

A progressive rollout has:

• Base attribute

  The entity attribute used for bucketing, such as user.id or team.id.

• Starting variant

  The value served before the rollout begins, such as Off.

• Target variant

  The value users move toward during the rollout, such as On.

• Fallback variant

  The value served if the base attribute is missing or is not a string.

• Schedule

  The percentages and durations Vercel Flags uses to move traffic toward the target variant.

For example:

{
  "user": {
    "id": "user_123",
    "plan": "pro"
  }
}

If the rollout is based on user.id, Vercel Flags uses user_123 to assign the user to a stable rollout bucket. As the rollout percentage increases, users already receiving the target variant stay in that variant, and additional users move from the starting variant to the target variant.

Use a stable, high-cardinality base attribute, such as user.id or team.id. Avoid low-cardinality attributes such as user.plan, because many users share the same value and land in the same rollout bucket.

If the base attribute is missing or is not a string, Vercel Flags returns the fallback variant. Gradual rollout outcomes can be used as the outcome of a rule or as the fallback outcome when no direct targets or rules match.

Segments are reusable targeting rules. You can create a segment for a group, such as team members, and reuse that segment across multiple feature flags and rules.

Segments help you maintain targeting logic in one place instead of recreating the same rule in multiple flags.

• Vercel Flags
• Feature Flag Configuration
• Entities
• Using the Flags SDK with Vercel Flags