Feature Flags & Progressive Rollouts#

The most dangerous moment in software is deployment. Feature flags eliminate the risk by decoupling deployment from release — code ships to production but stays hidden until you're ready.

The Problem#

Without flags:

Deploy new checkout → 100% of users get it immediately
Bug in new checkout → 100% of users affected
Rollback → redeploy old version (5-30 minutes downtime)

With flags:

Deploy new checkout (flag OFF) → 0% of users see it
Enable for 5% → monitor errors → looks good
Ramp to 25% → 50% → 100%
Bug found at 25%? → flip flag OFF instantly (< 1 second)

Types of Feature Flags#

1. Release Flags (Temporary)#

Gate new features during rollout. Remove after 100% launch.

if (flags.isEnabled("new-checkout", user)) {
  return <NewCheckout />;
}
return <OldCheckout />;

2. Experiment Flags (A/B Tests)#

Compare two versions to measure which performs better.

const variant = flags.getVariant("pricing-page", user);
// variant: "control" | "variant-a" | "variant-b"

3. Ops Flags (Kill Switches)#

Disable expensive features during incidents.

if (flags.isEnabled("recommendations-engine")) {
  return await getRecommendations(user);
}
return []; // graceful degradation

4. Permission Flags (Long-lived)#

Gate features by plan, role, or entitlement.

if (flags.isEnabled("advanced-exports", user)) {
  return <ExportModal showPro={true} />;
}

Progressive Rollout Strategies#

Percentage Rollout#

Day 1: 1% of users (internal + beta)
Day 2: 5% (monitor error rates)
Day 3: 25% (monitor performance)
Day 5: 50%
Day 7: 100% → remove flag

User Targeting#

Phase 1: Internal employees only
Phase 2: Beta program users
Phase 3: Users in US region
Phase 4: All users

Ring-Based Deployment#

Ring 0: Developers (dogfooding)
Ring 1: 1% canary users
Ring 2: 10% early adopters
Ring 3: 100% general availability

Architecture#

Client-Side Evaluation#

App starts → fetch flag config from CDN → evaluate locally
                                        → no server round-trip per check

Fast (< 1ms). Config updates via SSE/polling. Good for frontend.

Server-Side Evaluation#

Request → server evaluates flag → returns appropriate response

Secure (rules not exposed). Good for backend, API features.

Hybrid#

Frontend flags → client-side SDK (LaunchDarkly, PostHog)
Backend flags → server-side SDK
Both sync from same flag service

Implementation Patterns#

Simple In-Code#

// Don't do this in production (no remote control)
const FLAGS = {
  newCheckout: process.env.FEATURE_NEW_CHECKOUT === "true",
};

With Context (User Targeting)#

const flags = await flagService.evaluate({
  userId: user.id,
  email: user.email,
  plan: user.plan,      // "free" | "pro" | "enterprise"
  country: user.country,
  percentile: hash(user.id) % 100,  // stable percentage bucket
});

if (flags.newCheckout) {
  // User is in the rollout
}

Stable Bucketing#

Same user always gets same flag value (no flickering):

// hash(userId) % 100 gives stable 0-99 value
const bucket = murmurhash(userId) % 100;
const isEnabled = bucket < rolloutPercentage; // e.g., < 25 for 25%

Tools Compared#

Quick Decision#

• Enterprise with complex rules → LaunchDarkly
• Self-hosted + open source → Unleash or Flagsmith
• A/B testing + product analytics → PostHog or Statsig
• Simple + cheap → ConfigCat or env vars
• Next.js edge → Vercel Edge Config

Best Practices#

1. Temporary flags get removed — set expiry dates, track flag debt
2. Default to OFF — new flags should be disabled by default
3. Stable bucketing — same user always sees same variant
4. Flag naming convention — feature.new-checkout, ops.disable-recommendations
5. Monitor per-flag metrics — error rates, latency, conversion per cohort
6. Don't nest flags — if (flagA && flagB && !flagC) is unmaintainable
7. Audit trail — log who changed what flag when

Anti-Patterns#

1. Flag debt — 500 flags, nobody knows which are active. Clean up after launch.
2. Flags in database queries — checking flags inside SQL WHERE clauses
3. Testing without flags — tests should cover both flag-on and flag-off paths
4. Flags as config — feature flags are temporary. Use config for permanent settings.

Architecture Example#

Client SDK → Flag Service (CDN-cached config)
                ↓ SSE stream (real-time updates)
           → Evaluate flag for user context
           → Render appropriate UI

Server SDK → Flag Service (server-side eval)
                ↓
           → Return flagged API response

Flag Service:
  → Dashboard (create/edit flags)
  → Targeting rules (%, user attributes, segments)
  → Audit log
  → Metrics (per-flag impact)

Design your deployment architecture at codelit.io — generate interactive diagrams with CI/CD exports.

Summary#

1. Decouple deploy from release — ship code anytime, enable when ready
2. Progressive rollout — 1% → 5% → 25% → 100%, monitoring at each step
3. Kill switches for graceful degradation during incidents
4. A/B tests for data-driven decisions
5. Clean up flag debt — every flag should have an owner and expiry
6. Stable bucketing — hash user ID, not random per request

---

118 articles on system design at codelit.io/blog.