Feature Flags

Feature flags (also called feature toggles) are conditional statements in your code that control whether a feature is visible or active for a given user. Instead of deploying new code to enable a feature, you flip a switch in the Flagpool dashboard.

How feature flags work

At their simplest, feature flags wrap existing code in a conditional check:

if (client.isEnabled('new-checkout')) {
  showNewCheckout()
} else {
  showOldCheckout()
}

The flag value is determined by:

1. Whether the flag is enabled for the current environment
2. Targeting rules — conditions that match against the user context
3. Rollout percentage — what fraction of users should see the feature
4. Default variation — the fallback value when no rules match

All of this evaluation happens locally inside your application. The SDK downloads flag configurations from the Flagpool CDN and evaluates them in-process — no network round-trip per check.

Why use feature flags?

Use case	How flags help
Safer deployments	Deploy code with features hidden. Enable when ready.
Progressive rollouts	Release to 1%, then 10%, then 50%, then 100% of users.
Targeted releases	Show features only to beta testers, enterprise customers, or specific regions.
Kill switches	Instantly disable a broken feature without redeploying.
A/B testing	Serve different variations to different user groups and measure impact.
Trunk-based development	Merge incomplete features to main behind a flag.
Entitlements	Gate features by subscription plan (free, pro, enterprise).

Evaluation order

When a flag is evaluated, the SDK follows this order:

1. Rules — sorted by priority (lowest number = highest priority). The first matching rule determines the returned variation.
2. Rollout — if no rules match, the SDK checks whether the user falls within the rollout percentage.
3. Default variation — if in rollout (or rollout is 100%), the default "on" variation is returned.
4. Off variation — if the user is outside the rollout, the "off" variation (index 1) is returned.

This evaluation is deterministic: given the same flag configuration and user context, the result is always the same.

Flag lifecycle

A typical feature flag goes through these stages:

Create → Test in Dev → Validate in Staging → Roll out in Production → Clean up code

1. Create the flag in the dashboard before deploying code that references it
2. Test in the Development environment with the flag toggled on
3. Validate in Staging under realistic conditions
4. Roll out gradually in Production (start small, increase over time)
5. Clean up — once the feature is fully shipped, remove the flag check from code and archive the flag

Stale flags add complexity. Flagpool provides automatic stale flag detection on paid plans to help you identify flags that should be cleaned up.

Next steps

• Flag Types — boolean, string, number, and JSON flags
• Environments — manage flags across dev, staging, and production
• Targeting — control who sees what
• Rollouts — percentage-based releases