Feature Flags: Implementation Guide

TL;DR

• Bottom line: Feature flags decouple deployment from release -- ship code to production without exposing it to users, then control visibility at runtime.
• Key tool: Boolean, percentage, and user-segment flags evaluated server-side with local caching.
• Watch out for: Flag debt -- every flag left active past its rollout becomes technical debt. Remove flags within 30 days of full rollout.
• Works with: Any language/framework. Managed services (LaunchDarkly, Unleash, Flagsmith) or custom implementations with config stores (database, Redis, environment variables).

Constraints

• Never expose flag evaluation logic to the client in security-sensitive contexts -- server-side evaluation prevents users from toggling flags via browser devtools
• Always provide a default fallback value when evaluating a flag -- if the flag service is unreachable, the application must not crash or expose unfinished features
• Never use feature flags to gate security controls (authentication, authorization, encryption) -- a misconfigured flag could disable security entirely
• Remove feature flags within 30 days of full rollout -- stale flags accumulate as technical debt and create untested code paths [src4]
• Test both flag-on and flag-off paths in CI -- untested branches become landmines in production [src2]

Quick Reference

[src1]

Decision Tree

START
|-- Need to gradually roll out a new feature?
|   |-- YES --> Use a Release Toggle with percentage rollout (see Step 2)
|   +-- NO |
|-- Need to run an experiment (A/B test)?
|   |-- YES --> Use an Experiment Toggle with user segmentation
|   +-- NO |
|-- Need emergency disable capability?
|   |-- YES --> Use a Kill Switch (permanent, simple boolean)
|   +-- NO |
|-- Need to gate features by user plan/tier?
|   |-- YES --> Use a Permission Toggle (long-lived, user-attribute based)
|   +-- NO |
|-- Need to degrade non-critical services under load?
|   |-- YES --> Use an Ops Toggle (circuit breaker pattern)
|   +-- NO |
+-- DEFAULT --> Use a Release Toggle for trunk-based development

Step-by-Step Guide

1. Define a flag evaluation interface

Create a clean abstraction so your business logic does not depend on a specific flag provider. This lets you swap between custom implementations and managed services. [src2]

// flag-service.ts -- minimal interface for flag evaluation
interface FlagService {
  isEnabled(flagKey: string, context?: FlagContext): boolean;
  getVariant(flagKey: string, context?: FlagContext): string;
}

interface FlagContext {
  userId?: string;
  email?: string;
  country?: string;
  plan?: string;
  percentageSeed?: number;  // stable hash for consistent bucketing
}

Verify: Ensure your interface supports boolean flags and multi-variant flags with user context.

2. Implement percentage rollout

Use consistent hashing so the same user always sees the same variant. Never use Math.random() -- it causes flickering between page loads. [src7]

// percentage-rollout.ts
import { createHash } from 'crypto';

function isEnabledForPercentage(
  flagKey: string, userId: string, percentage: number
): boolean {
  const hash = createHash('md5')
    .update(`${flagKey}:${userId}`).digest('hex');
  const bucket = parseInt(hash.substring(0, 8), 16) % 100;
  return bucket < percentage;
}

Verify: Call isEnabledForPercentage('flag', 'user-123', 50) multiple times -- it must return the same value every time.

3. Add targeting rules

Layer targeting rules on top of percentage rollout for fine-grained control. Evaluate rules in priority order: explicit overrides first, then segments, then percentage. [src5]

function evaluateFlag(config: FlagConfig, ctx: FlagContext): boolean {
  if (!config.enabled) return false;
  if (ctx.userId && ctx.userId in config.overrides) {
    return config.overrides[ctx.userId];
  }
  for (const rule of config.rules) {
    if (matchesRule(rule, ctx)) return rule.enabled;
  }
  if (ctx.userId) {
    return isEnabledForPercentage(config.key, ctx.userId, config.percentage);
  }
  return false;
}

Verify: Test with an overridden user, a rule-matched user, and a percentage-only user.

4. Implement flag cleanup automation

Set expiration dates at creation time and enforce them in CI. This is the most important step -- skipping it guarantees flag debt. [src4]

function checkExpiredFlags(registry: FlagRegistration[]): string[] {
  const now = new Date();
  return registry
    .filter(f => f.expiresAt && f.expiresAt < now)
    .map(f => `EXPIRED: ${f.key} (owner: ${f.owner})`);
}
// CI pipeline: fail build if checkExpiredFlags() returns non-empty

Verify: checkExpiredFlags(registry) should return an empty array in a healthy codebase.

Code Examples

Node.js: Custom Feature Flag Service with Redis

// Input:  Redis connection URL, flag configs stored as JSON
// Output: Boolean flag evaluation with percentage rollout

const Redis = require('ioredis');       // [email protected]
const crypto = require('crypto');

class FeatureFlagService {
  constructor(redisUrl) {
    this.redis = new Redis(redisUrl);
    this.cache = new Map();             // local cache, 30s TTL
  }

  async isEnabled(flagKey, userId, fallback = false) {
    try {
      const config = await this.getConfig(flagKey);
      if (!config || !config.enabled) return false;
      if (config.overrides?.[userId] !== undefined) {
        return config.overrides[userId];
      }
      if (config.percentage < 100) {
        const hash = crypto.createHash('md5')
          .update(`${flagKey}:${userId}`).digest('hex');
        return (parseInt(hash.slice(0, 8), 16) % 100) < config.percentage;
      }
      return true;
    } catch (err) {
      return fallback;  // always return fallback on error
    }
  }
}

Python: Custom Feature Flag with Database Backend

# Input:  PostgreSQL connection, flag configs in flags table
# Output: Boolean flag evaluation with user targeting

import hashlib
from typing import Optional
import psycopg2  # psycopg2-binary==2.9.x

class FeatureFlagService:
    def __init__(self, dsn: str):
        self.conn = psycopg2.connect(dsn)

    def is_enabled(self, flag_key: str, user_id: str, fallback: bool = False) -> bool:
        try:
            config = self._get_config(flag_key)
            if not config or not config["enabled"]:
                return False
            if user_id in config.get("overrides", {}):
                return config["overrides"][user_id]
            pct = config.get("percentage", 100)
            if pct < 100:
                h = hashlib.md5(f"{flag_key}:{user_id}".encode()).hexdigest()
                return int(h[:8], 16) % 100 < pct
            return True
        except Exception:
            return fallback

Go: Feature Flag Middleware for HTTP

// Input:  Flag config map, HTTP request with user context
// Output: HTTP middleware that injects flag values into request context

func (fs *FlagService) IsEnabled(flagKey, userID string) bool {
    config, ok := fs.flags[flagKey]
    if !ok || !config.Enabled { return false }
    if val, exists := config.Overrides[userID]; exists { return val }
    if config.Percentage < 100 {
        hash := md5.Sum([]byte(flagKey + ":" + userID))
        bucket := binary.BigEndian.Uint32(hash[:4]) % 100
        return int(bucket) < config.Percentage
    }
    return true
}

Node.js: Unleash SDK Integration

// Input:  Unleash server URL, API token
// Output: Feature flag evaluation via managed service

const { initialize } = require('unleash-client');  // [email protected]

const unleash = initialize({
  url: 'https://unleash.example.com/api',
  appName: 'my-app',
  customHeaders: { Authorization: process.env.UNLEASH_API_KEY },
  refreshInterval: 15000,
});

unleash.on('ready', () => {
  const context = { userId: user.id, properties: { plan: user.plan } };
  if (unleash.isEnabled('premium-feature', context)) {
    enablePremiumFeature();
  }
});

Anti-Patterns

Wrong: Feature flag wrapping deeply nested code

// BAD -- flag check buried inside business logic
function processOrder(order) {
  validateItems(order.items);
  if (featureFlags.isEnabled('new-shipping')) {  // buried deep
    applyNewShipping(order);
    if (featureFlags.isEnabled('new-tracking')) {  // nested flags!
      enableTracking(order);
    }
  } else { applyOldShipping(order); }
}

Correct: Feature flag evaluated once at the boundary

// GOOD -- evaluate at the entry point, pass result down
app.post('/orders', (req, res) => {
  const features = {
    useNewShipping: flags.isEnabled('new-shipping', req.user.id),
  };
  processOrder(req.body, features);
});

[src1]

Wrong: No expiration tracking on release flags

// BAD -- flag with no lifecycle management
await redis.set('flag:new-dashboard', JSON.stringify({
  enabled: true, percentage: 100,
  // No owner, no expiration -- lives forever
}));

Correct: Flag with lifecycle metadata

// GOOD -- every flag has an owner and expiration
await redis.set('flag:new-dashboard', JSON.stringify({
  enabled: true, percentage: 100,
  owner: 'frontend-team', createdAt: '2026-02-01',
  expiresAt: '2026-03-15', jiraTicket: 'FE-4521', type: 'release',
}));

[src4]

Wrong: Using Math.random() for percentage rollout

# BAD -- random gives different results on every evaluation
import random
def is_enabled(flag_key, user_id, percentage):
    return random.random() * 100 < percentage  # flickers every request!

Correct: Stable hash-based bucketing

# GOOD -- same user always gets same bucket
import hashlib
def is_enabled(flag_key, user_id, percentage):
    h = hashlib.md5(f"{flag_key}:{user_id}".encode()).hexdigest()
    return int(h[:8], 16) % 100 < percentage  # deterministic per user

[src7]

Wrong: Flag dependencies without explicit ordering

// BAD -- flag B depends on flag A, but no explicit relationship
if (flags.isEnabled('new-api') && flags.isEnabled('new-api-v2')) {
  // Undefined behavior if new-api is off but new-api-v2 is on
}

Correct: Explicit flag dependency declaration

// GOOD -- declare dependencies in flag config
const flagConfig = {
  'new-api-v2': {
    enabled: true, dependsOn: ['new-api'], percentage: 50,
  },
};

[src2]

Common Pitfalls

• Flag flickering: Using non-deterministic randomness for percentage rollout causes users to see features appear and disappear. Fix: use stable hashing with md5(flagKey + userId) for consistent bucketing. [src7]
• Stale flag accumulation: Teams create flags but never clean them up, leading to thousands of dead code paths. Fix: set expiration dates at creation, fail CI on expired flags. [src4]
• Testing only the happy path: Only testing the flag-on path means the flag-off path rots silently. Fix: run CI with ALL_FLAGS=on and ALL_FLAGS=off matrix. [src2]
• Flag evaluation in hot loops: Evaluating flags inside tight loops when the value is the same for all items. Fix: evaluate once before the loop and store the result. [src6]
• No centralized flag dashboard: Teams manage flags in scattered config files, losing track of what flags exist. Fix: use a centralized flag service or registry. [src3]
• Coupling deployment and flag state: Deploying new code and enabling the flag simultaneously defeats the purpose. Fix: deploy first with the flag off, verify stability, then enable separately. [src5]

Diagnostic Commands

# List all feature flags in a Redis-backed system
redis-cli KEYS "flag:*" | while read key; do echo "$key: $(redis-cli GET $key)"; done

# Find all flag references in codebase (grep for cleanup)
grep -rn "isEnabled\|is_enabled\|IsEnabled\|feature_flag" --include="*.ts" --include="*.py" --include="*.go" src/

# Check for expired flags in a JSON config file
cat flags.json | python3 -c "
import json, sys
from datetime import datetime
flags = json.load(sys.stdin)
now = datetime.now().isoformat()[:10]
for k, v in flags.items():
    exp = v.get('expiresAt')
    if exp and exp < now:
        print(f'EXPIRED: {k} (expired {exp}, owner: {v.get(\"owner\", \"unknown\")})')
"

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Feature flag evaluation adds latency. For managed services with streaming SDKs (LaunchDarkly, Unleash), local evaluation takes <1ms. For remote API calls, expect 20-100ms. Cache aggressively.
• Flag combinatorial explosion: with N boolean flags, you have 2^N possible code paths. At 20 flags, that is over 1 million paths. Keep active flag count under 50.
• Client-side flags (browser/mobile) can be inspected and manipulated by users. Never use client-side evaluation for security-sensitive gates.
• Percentage rollout is only consistent if you use the same hashing algorithm and seed everywhere. If your Node.js and Python services hash differently, a user might see the feature in one service but not another.
• Uber built Piranha, an automated tool to remove stale feature flags. Consider building similar automation if you have >100 flags.