Skip to content
feat.so feat.so

Feature flags

A feature flag is the named decision your code asks feat about. It carries a key, a value type, a set of variations, and a state per environment.

Anatomy of a flag

Section titled “Anatomy of a flag”
key:          checkout-v2
name:         Checkout v2
value type:   boolean
variations:
  - true
  - false
description:  Routes traffic to the rewritten checkout flow.
maintainer:   alice@example.com
  • Key. The string your code passes to the SDK. Immutable after the flag is created. Use lowercase kebab-case (checkout-v2, new-onboarding).
  • Value type. One of boolean, string, number, or json. Immutable after the flag is created, because every variation’s value has to be that type.
  • Variations. The possible values the flag can return. A boolean flag has exactly two (true/false); other types can have more. See Variations.
  • Name and description. For humans. Edit freely.
  • Maintainer (optional, off by default). The team member responsible for the flag. Used for search and ownership. Enable from Organization features under “flag maintainer.”

State per environment

Section titled “State per environment”

The flag definition is shared across every environment in the project. The flag’s state in each environment is independent:

  • Whether targeting is on or off.
  • Which variation is served when targeting is off (the off-variation).
  • The default rule, served when targeting is on but no targeting rule matches.
  • Any targeting rules, individual targets, scheduled changes, and approvals.

So checkout-v2 can be live for 100% of traffic in development, gated to your internal team in staging, and off in production, all at once.

Lifecycle

Section titled “Lifecycle”

A flag has three lifecycle states:

StateWhat it means
ActiveThe flag is in use. Targeting runs as configured.
ArchivedThe flag is preserved for audit but skipped by evaluation. SDKs return the supplied default with reason: DISABLED.
DeletedThe flag is removed. Within the grace period an admin can restore it; after that it is gone.

Archive a flag once you have removed every reference to its key from your code, but you still want the audit history. Delete it when you no longer need that history either.

Naming and hygiene

Section titled “Naming and hygiene”

A flag whose value never changes again is technical debt. The discipline that keeps a flag system healthy:

  • Use one key per concept. Resist the urge to repurpose checkout-v2 for a different rollout.
  • Tag the flag’s intent in its description: “permanent kill switch” vs “temporary rollout, remove after 2026-08.”
  • Archive temporary flags as soon as you remove the code path they guarded.
  • Use the audit log to see who last touched a flag and when.
Section titled “Related”