Feature Flags: Progressive Rollouts and Safe Deployments

Feature flags decouple deployment from release. This guide covers implementation patterns, best practices, and lifecycle management.

What Are Feature Flags?#

Feature flags are conditional statements that control feature visibility at runtime:

if (featureFlags.isEnabled('new-checkout')) {
  return <NewCheckout />;
}
return <LegacyCheckout />;

Types of Feature Flags#

Release Flags#

Control feature rollout:

const flags = {
  'new-dashboard': {
    enabled: true,
    rolloutPercentage: 25, // 25% of users
    enabledForUsers: ['beta-testers'],
  },
};

Experiment Flags#

A/B testing:

const experiments = {
  'checkout-button-color': {
    variants: ['blue', 'green', 'orange'],
    distribution: [0.33, 0.33, 0.34],
  },
};

Operational Flags#

Kill switches:

const operationalFlags = {
  'enable-caching': true,
  'rate-limit-api': true,
  'maintenance-mode': false,
};

Implementation#

Basic Feature Flag Service#

interface FeatureFlag {
  key: string;
  enabled: boolean;
  rolloutPercentage?: number;
  targetedUsers?: string[];
  targetedGroups?: string[];
}

class FeatureFlagService {
  private flags: Map<string, FeatureFlag>;

  constructor(flags: FeatureFlag[]) {
    this.flags = new Map(flags.map(f => [f.key, f]));
  }

  isEnabled(key: string, context?: UserContext): boolean {
    const flag = this.flags.get(key);
    if (!flag) return false;
    if (!flag.enabled) return false;

    // Check targeted users
    if (flag.targetedUsers?.includes(context?.userId)) {
      return true;
    }

    // Check targeted groups
    if (flag.targetedGroups?.some(g => context?.groups.includes(g))) {
      return true;
    }

    // Check rollout percentage
    if (flag.rolloutPercentage !== undefined) {
      const hash = this.hashUser(context?.userId || 'anonymous', key);
      return hash < flag.rolloutPercentage;
    }

    return flag.enabled;
  }

  private hashUser(userId: string, flagKey: string): number {
    const combined = `${userId}-${flagKey}`;
    let hash = 0;
    for (let i = 0; i < combined.length; i++) {
      hash = ((hash << 5) - hash) + combined.charCodeAt(i);
      hash = hash & hash;
    }
    return Math.abs(hash) % 100;
  }
}

React Integration#

import { createContext, useContext, ReactNode } from 'react';

const FeatureFlagContext = createContext<FeatureFlagService | null>(null);

export function FeatureFlagProvider({
  children,
  service,
}: {
  children: ReactNode;
  service: FeatureFlagService;
}) {
  return (
    <FeatureFlagContext.Provider value={service}>
      {children}
    </FeatureFlagContext.Provider>
  );
}

export function useFeatureFlag(key: string): boolean {
  const service = useContext(FeatureFlagContext);
  const user = useCurrentUser();

  if (!service) {
    throw new Error('useFeatureFlag must be used within FeatureFlagProvider');
  }

  return service.isEnabled(key, {
    userId: user?.id,
    groups: user?.groups || [],
  });
}

// Usage
function Dashboard() {
  const showNewWidget = useFeatureFlag('new-dashboard-widget');

  return (
    <div>
      {showNewWidget && <NewWidget />}
      <LegacyContent />
    </div>
  );
}

Server-Side Implementation#

// middleware/featureFlags.ts
import { NextRequest, NextResponse } from 'next/server';

export async function middleware(request: NextRequest) {
  const flags = await fetchFeatureFlags();
  const userId = request.cookies.get('user-id')?.value;

  // Add flags to request headers for downstream use
  const response = NextResponse.next();
  response.headers.set('x-feature-flags', JSON.stringify(
    evaluateFlags(flags, { userId })
  ));

  return response;
}

Progressive Rollout Strategy#

Staged Rollout#

const rolloutStages = [
  { percentage: 1, duration: '1h', name: 'canary' },
  { percentage: 10, duration: '4h', name: 'early-adopters' },
  { percentage: 50, duration: '24h', name: 'half-rollout' },
  { percentage: 100, duration: null, name: 'full-release' },
];

async function advanceRollout(flagKey: string) {
  const flag = await getFlag(flagKey);
  const currentStage = rolloutStages.findIndex(
    s => s.percentage === flag.rolloutPercentage
  );

  if (currentStage < rolloutStages.length - 1) {
    const nextStage = rolloutStages[currentStage + 1];

    // Check error rates before advancing
    const errorRate = await getErrorRate(flagKey);
    if (errorRate > 0.01) { // 1% threshold
      await rollback(flagKey);
      return;
    }

    await updateFlag(flagKey, {
      rolloutPercentage: nextStage.percentage,
    });
  }
}

Monitoring Integration#

function trackFeatureFlagUsage(
  flagKey: string,
  enabled: boolean,
  context: UserContext
) {
  analytics.track('feature_flag_evaluated', {
    flag: flagKey,
    enabled,
    userId: context.userId,
    timestamp: Date.now(),
  });
}

// Track errors associated with flags
function trackError(error: Error, activeFlags: string[]) {
  errorTracking.captureException(error, {
    tags: {
      activeFeatureFlags: activeFlags.join(','),
    },
  });
}

Flag Lifecycle Management#

Expiration and Cleanup#

interface FeatureFlagWithMetadata extends FeatureFlag {
  createdAt: Date;
  expiresAt?: Date;
  owner: string;
  status: 'active' | 'deprecated' | 'archived';
}

// Regular cleanup job
async function cleanupExpiredFlags() {
  const flags = await getAllFlags();
  const now = new Date();

  for (const flag of flags) {
    if (flag.expiresAt && flag.expiresAt < now) {
      // Notify owner before removal
      await notifyOwner(flag.owner, `Flag "${flag.key}" has expired`);

      // Check if flag is still in codebase
      const inCodebase = await searchCodebase(flag.key);
      if (!inCodebase) {
        await archiveFlag(flag.key);
      }
    }
  }
}

Documentation#

// flags.config.ts
export const featureFlags = {
  'new-checkout': {
    description: 'New streamlined checkout experience',
    owner: 'checkout-team',
    jiraTicket: 'SHOP-1234',
    createdAt: '2024-01-15',
    expectedRemoval: '2024-03-01',
    dependencies: ['new-payment-provider'],
  },
} as const;

Best Practices#

1. Keep Flags Short-Lived#

// Flag should be removed once feature is stable
// Bad: flags that exist for years
// Good: remove within 2-4 weeks of full rollout

2. Use Descriptive Names#

// Bad
'flag-123'
'test-feature'

// Good
'checkout-one-click-purchase'
'dashboard-analytics-v2'

3. Default to Off for New Features#

const defaultFlagState = {
  enabled: false, // Safe default
  rolloutPercentage: 0,
};

4. Test Both States#

describe('Checkout', () => {
  it('works with new checkout enabled', () => {
    setFeatureFlag('new-checkout', true);
    // test new checkout
  });

  it('works with new checkout disabled', () => {
    setFeatureFlag('new-checkout', false);
    // test legacy checkout
  });
});

Common Pitfalls#

Flag explosion: Too many flags become unmanageable
Stale flags: Old flags left in codebase
Testing gaps: Not testing both flag states
Performance impact: Evaluating too many flags per request

Conclusion#

Feature flags enable safer deployments and progressive rollouts. Implement a clear lifecycle from creation to removal, monitor flag impact, and maintain discipline around flag cleanup.

Share this article