Core concepts

Feature Flags is built around a small set of concepts you will use every day.

Flag

A flag is a named value you read from code.

checkoutV2
pricingPageVariant
maxUploadMb

Use clear, stable names. Treat them like public product API.

Default

The default is the value every request gets when nothing more specific applies.

checkoutV2: flag.boolean({
  default: false,
})

Choose a default that keeps the app safe when a flag is new, unpublished, or not targeted to the current request.

Environment Override

An environment override gives one value to preview, another to staging, and another to prod.

checkoutV2: flag.boolean({
  default: false,
  environments: {
    preview: true,
    prod: false,
  },
})

Use environment overrides for release timing, operational toggles, and app-wide values that change by environment.

Rule

A rule chooses a value for a subset of traffic.

The supported rule kinds are:

• tenant
• user
• attribute
• percentage

Keep the rules from most specific to most general. That makes the rollout easy to reason about later.

Decision

An evaluation returns a decision:

• the key that was read
• the selected value
• the reason that value won
• the matched rule ID, when a rule matched
• the version and checksum of the published snapshot

Use the decision form when you need to debug why a user saw a specific value.