Feature Flags

When to Use

• Use when: releasing a risky feature to a subset of users before full rollout
• Use when: you need an instant kill switch without a redeploy
• Use when: running an experiment (A/B test) behind a flag
• Use when: cleaning up stale flags that are 100% rolled out or removed
• Do NOT use for: infra-level canary deploys — those live in the deployment pipeline
• Do NOT use for: config values that never change — use env vars instead

Flag Types

Use the narrowest type that fits. Release toggles are the most common source of flag debt.

Lifecycle

1. CREATE   — name, type, default (off), owner, expiry date
2. TARGET   — specify who sees it (user IDs, segments, attributes)
3. ROLLOUT  — ramp percentage: 1% → 5% → 25% → 100%
4. CLEAN UP — remove flag + code path within TTL after full rollout

Default must always be the safe/old behavior — flag ON = new behavior.

SDK Usage Patterns

LaunchDarkly (Node.js)

import * as ld from '@launchdarkly/node-server-sdk';

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

// Always pass a context (replaces the old "user" object)
const ctx = { kind: 'user', key: user.id, plan: user.plan, country: user.country };

const newCheckout = await client.variation('new-checkout-flow', ctx, false); // false = default

if (newCheckout) {
  return handleNewCheckout(cart);
} else {
  return handleLegacyCheckout(cart);
}

Unleash (Node.js)

import { initialize } from 'unleash-client';

const unleash = initialize({
  url: process.env.UNLEASH_URL,
  appName: 'my-service',
  customHeaders: { Authorization: process.env.UNLEASH_TOKEN },
});

// Context carries targeting attributes
const enabled = unleash.isEnabled('new-checkout-flow', {
  userId: user.id,
  properties: { plan: user.plan },
});

GrowthBook (Node.js)

import { GrowthBook } from '@growthbook/growthbook';

const gb = new GrowthBook({
  apiHost: process.env.GB_API_HOST,
  clientKey: process.env.GB_CLIENT_KEY,
  attributes: { id: user.id, plan: user.plan },
});
await gb.loadFeatures();

if (gb.isOn('new-checkout-flow')) {
  return handleNewCheckout(cart);
}

Gradual Rollout Strategy

Day 0:   Internal users only (flag ON for employee accounts)
Day 1:   1% — catch crashes before they scale
Day 2:   5% — confirm p99 latency unchanged
Day 3:   25% — validate at meaningful traffic
Day 5:   100% — complete rollout
Day 7+:  Remove flag + dead code path

Monitor error rate and p99 latency at each step. Roll back by flipping flag to 0% — no deploy needed.

Kill Switch Pattern

An ops flag that is ON by default — flipping it OFF disables the feature.

// Kill switch: default TRUE (feature running normally)
const paymentsEnabled = await client.variation('payments-kill-switch', ctx, true);

if (!paymentsEnabled) {
  return { error: 'Payments temporarily unavailable. Please try again later.' };
}

Rules:

• Kill switches are long-lived — do not put an expiry on them
• Name them clearly: {feature}-kill-switch or {feature}-enabled
• Test the OFF path explicitly — it's the path that matters in an incident

Targeting Rules

Rollout order: internal → beta users → low-value cohort → geo subset → percentage ramp.

Context attributes to expose: user.id (stable, for consistent bucketing), user.plan, user.country, request.env.

Never target by email — IDs ensure consistent bucketing across sessions.

Testing with Flags

Inject flag state directly into functions — never call the SDK in unit tests.

// Both paths must be tested
it('new checkout when flag ON',  () => expect(checkout(cart, { newCheckoutFlow: true  })).toMatchNewShape());
it('legacy checkout when flag OFF', () => expect(checkout(cart, { newCheckoutFlow: false })).toMatchLegacyShape());

// Integration: mock the client
const mockClient = { variation: jest.fn().mockResolvedValue(true) };

A flag with only the ON path tested breaks silently when rolled back.

Flag Hygiene

Flag debt compounds: 50 stale flags means 50 conditional branches no one understands.

Anti-Fake-Pass Rules

Before claiming feature flag work is done, you MUST show:

• Default value is the safe/old behavior (flag OFF = no change for users)
• Both code paths have test coverage — ON and OFF
• Kill switch (if applicable) tested in the OFF state explicitly
• Context/user object passes a stable ID for consistent bucketing
• Expiry date or cleanup ticket created for release/experiment flags
• Rollout plan defined — not "flip to 100% and see what happens"
• Flag removed from code (not just dashboard) after full rollout

Reference: gates/anti-fake-pass-gate.md