Feature flags

Types and evaluation context

Tie flags to release flow: new behavior defaults off; during gray rollout watch errors and latency; after full rollout set a removal date or tech-debt ticket, and have the agent flag stale toggles in PRs.

• Defaults must degrade safely when config is unavailable (usually conservative: new behavior off).
• Do not hide unfinished auth, payments, or other compliance paths behind flags.
• Document production-critical flags and owners.

// LaunchDarkly Node.js SDK integration example
import * as ld from '@launchdarkly/node-server-sdk';

const client = ld.init(process.env.LD_SDK_KEY!);
await client.waitForInitialization();

// Evaluation context: user + organization + environment
const context: ld.LDContext = {
  kind: 'multi',
  user: { key: userId, email: user.email, plan: user.plan },
  org:  { key: orgId,  tier: org.tier },
};

// Release toggle: new feature defaults off
const newCheckout = await client.variation(
  'billing.new-checkout-flow',   // flag key (normalized naming)
  context,
  false                          // fallback default (when config service unreachable)
);

if (newCheckout) {
  return handleNewCheckout(cart);
} else {
  return handleLegacyCheckout(cart);  // old path must be kept until flag is removed
}

// Ops toggle (Kill Switch): emergency shutoff, no redeploy needed
// Set the flag to false in the console/API to take effect immediately

// Unleash Node.js SDK integration example (open-source alternative)
import { initialize } from 'unleash-client';

const unleash = initialize({
  url: 'https://unleash.internal/api/',
  appName: 'myapp',
  customHeaders: { Authorization: process.env.UNLEASH_TOKEN! },
});

// Flag type examples
// release: control new feature launch
const isNewUI = unleash.isEnabled('myapp.new-dashboard-ui', {
  userId: String(user.id),   // bucket by user ID (stable hash)
});

// experiment: A/B test, returns variant value
const variant = unleash.getVariant('myapp.checkout-button-color', {
  userId: String(user.id),
});
const buttonColor = variant.enabled ? variant.payload?.value : 'blue';

// ops: operational control, differentiated by environment
const rateLimitEnabled = unleash.isEnabled('ops.strict-rate-limit');

Progressive rollout

From internal/canary to percentage or bucketed full rollout: each step needs observable metrics and a rollback plan. Evaluation should use stable context (user id, tenant, request traits) so users do not see random flicker.

  [ Define flag: default off, namespace, owner ]
        │
        ▼
  ┌─────────────┐     Internal / fixed allowlist; validate behavior and fallback
  │ Small enable │
  └─────────────┘
        │
        ▼
  ┌─────────────┐     Percentage or buckets; watch errors, latency, funnels
  │ Widen gray   │──── Issues: lower % or flip off (see Kill switch)
  └─────────────┘
        │
        ▼
  ┌─────────────┐     After full on: removal date or ticket; delete dead paths
  │ Stabilize    │
  └─────────────┘

Kill switch

Operational switches cut new paths during incidents or overload: changes must be auditable; propagation delay must be known (client cache TTL, CDN, regions); verify core journeys still work when off.

  [ Alert / human: need immediate mitigation ]
        │
        ▼
  ┌─────────────┐     Set flag off (or safe default) in config or console
  │ Turn off new │──── Log actor, ticket, timestamp
  └─────────────┘
        │
        ▼
  ┌─────────────┐     Wait for cache/instances; spot-check key journeys
  │ Propagate    │
  └─────────────┘
        │
        ▼
  ┌─────────────┐     Stay off until root cause fixed; decide permanent removal
  │ Incident     │
  └─────────────┘

• Critical paths must not be “new implementation only”—no 500s or blank pages after kill.
• Align with on-call runbooks: which flag maps to which capability, who can change production.

Governance, defaults, and cleanup

Unify prefixes (team/domain), environment, and layering (default vs override) so one concept does not sprawl into many keys. In PR review: permanent if-chains, and tests for both off and on paths.

• Long-lived flags need a business owner and quarterly review; experiments need expiry.
• In CI: lint or report on stale comments or TODOs (FLAG_REMOVE_BY).

// Setting feature flag state in tests (Jest example)
import { FeatureFlagClient } from '../lib/feature-flags';

// Mock the entire SDK client
jest.mock('../lib/feature-flags');
const mockClient = FeatureFlagClient as jest.Mocked<typeof FeatureFlagClient>;

describe('Checkout with new-checkout-flow flag', () => {
  beforeEach(() => jest.clearAllMocks());

  it('uses new version when flag=ON', async () => {
    mockClient.prototype.isEnabled.mockResolvedValue(true);
    const result = await processCheckout(cart);
    expect(result.flow).toBe('new');
  });

  it('falls back to legacy when flag=OFF (fallback path must be tested)', async () => {
    mockClient.prototype.isEnabled.mockResolvedValue(false);
    const result = await processCheckout(cart);
    expect(result.flow).toBe('legacy');
  });

  it('uses default value false when config service is unavailable', async () => {
    mockClient.prototype.isEnabled.mockRejectedValue(new Error('timeout'));
    const result = await processCheckout(cart);
    expect(result.flow).toBe('legacy');  // degraded default value
  });
});

Flag key normalization

Turn draft names into stable keys: lowercase, hyphen-separated words, only a-z, 0-9, ., - (works with most SDKs and config stores). Input below is normalized; empty after stripping means an invalid key.