Feature Flags

Imagine pushing code to production on a Friday afternoon without panicking. No massive release branches, no scary database migrations at midnight, and no immediate need to roll back an entire deployment if a bug appears.

That is the power of feature flags (also known as feature toggles).

What is a Feature Flag?

At its simplest level, a feature flag is just a basic conditional check in your code:

if (isNewFeatureEnabled) {
  renderNewFeature();
} else {
  renderOldFeature();
}

While this simple if/else logic represents the core concept, real-world feature flagging goes much deeper. It introduces a mechanism to change that boolean condition dynamically at runtime—without modifying code, restarting applications, or redeploying your service.

Key Use Cases

• Progressive Rollout: Enable a new checkout flow for 1% of users, then 10%, then 100% as confidence grows.
• Canary Releases: Expose raw or experimental features to a small internal group or beta testers before everyone else sees them.
• A/B Testing: Compare two different implementations with distinct user groups to measure conversion metrics.
• Role-Based Access: Enable features exclusively for admins, beta testers, or specific user tiers.
• Emergency Kill Switch: Instantly disable a problematic feature without re-triggering CI/CD pipelines.
• Decoupling Deployment from Release: Deploy code to production whenever it's merged, but keep it hidden behind a disabled flag until marketing or business teams are ready to launch.

The Feature Flag Architecture

To understand how dynamic evaluation works behind the scenes, it helps to look at the overall system flow. A standard feature flag architecture connects four key pieces:

+---------------------+           +------------------------+
|    Toggle Router    | <-------> |  Toggle Configuration  |
| (Evaluation Engine) |           |  (Server / Dashboard)  |
+---------------------+           +------------------------+
          ^
          | Context (e.g. userId, role)
          v
+---------------------+
|    Toggle Point     |
|   (if/else code)    |
+---------------------+

• Toggle Point: The conditional if/else statement inside your application source code.
• Toggle Context: Runtime attributes passed during evaluation (e.g., userId, role, IP address).
• Toggle Router: The evaluation engine that computes whether a flag is active based on context.
• Toggle Configuration: The centralized management system or database storing active toggle rules.

The Four Types of Feature Flags

Not all flags serve the same purpose. They are generally categorized by their Longevity (how long they live in your code) and Dynamism (how often their values change).

Release toggles should be aggressively cleaned up after a feature hits 100%, whereas Ops toggles stay in the code indefinitely as safety switches.

Manual Flags vs. Automated Management Systems

1. Manual / Non-Automatic Flags (Environment Variables)

When starting out, developers often use basic environment variables.

// naive-toggle.ts
interface User {
  id: string;
  role: 'admin' | 'user';
}

export class ManualFeatureService {
  static isNewDashboardEnabled(user: User): boolean {
    const globalFlag = process.env.ENABLE_NEW_DASHBOARD === 'true';
    const isAdmin = user.role === 'admin';

    return globalFlag || isAdmin;
  }
}

Why manual flags fall short:

• Deployment Bottlenecks: Toggling an environment variable usually requires restarting app instances or pods.
• No Sticky Rollouts: Implementing percentage-based rollouts manually requires writing custom hashing logic so users don't see flipping UIs on refresh.
• No Central Dashboard: There is no single interface showing who turned what on, when, and for whom.

2. Automated Flag Management (How Unleash Works)

Automated flag management platforms—such as Unleash (one of several popular enterprise and open-source flag engines)—separate flag rules from application code entirely.

Backend SDKs vs. Frontend SDKs

According to the official Unleash architecture, how flags evaluate depends on where your code runs:

• Backend SDKs (e.g., Node.js, Go, Java): Connect via the Client API. They fetch all feature flag rules and activation strategies from the Unleash server, store them in-memory, and evaluate flags locally. This makes flag checks extremely fast and keeps sensitive user data inside your application.
• Frontend SDKs (e.g., React, Mobile): Connect via the Frontend API or Unleash Edge. Because evaluation rules should not be exposed to end-user browsers, flag evaluation happens server-side, and the client receives pre-evaluated flag states for a given context.

Core Concepts: Activation Strategies vs. Strategy Variants

To understand how tools like Unleash manage releases without overwhelming complexity, it helps to remember two core concepts:

• Activation Strategies decide WHO gets access. This determines if a user qualifies for the feature flag at all. Examples include Gradual Rollout (e.g., "enable for 50% of traffic"), User IDs (e.g., "enable for beta testers"), or Targeting Constraints (e.g., "only if user location is US").
• Strategy Variants decide WHAT VERSION they see. Once a user qualifies via an activation strategy, variants determine which variation of the feature is delivered (e.g., "Out of the 50% of users who get the feature, 50% see Variant A and 50% see Variant B"). Variants can even return dynamic payloads like JSON or custom strings.

Putting It Together: A Real-World Example

In practice, Unleash lets you stack these concepts together seamlessly:

[ All Traffic ]
       │
       ▼ (Strategy: Gradual Rollout @ 50%)
[ 50% Qualified Traffic ]
       │
       ▼ (Constraint: country === 'US')
[ US Users in the 50% Bucket ]
       │
       ├──── 50% ────► [ Variant A: Red Checkout Button ]
       └──── 50% ────► [ Variant B: Green Checkout Button ]

1. You set a Gradual Rollout strategy to target 50% of your total users using consistent hashing so a user's experience remains sticky across reloads.
2. You add a Constraint so that only users in the US region within that 50% sample evaluate to true.
3. You attach Strategy Variants to split those qualifying US users 50/50 between two new checkout button designs to run an A/B test.

This separation keeps your application code clean while moving all targeting logic, rollout percentages, and experiment setups entirely into the management dashboard.

Code Example: Node.js Integration with Unleash

Here is how to set up Unleash correctly in a Node.js backend service:

import { startUnleash, Unleash } from 'unleash-client';
import express from 'express';

let unleashInstance: Unleash;
/**
 * `await startUnleash()` pauses execution until the SDK completes its initial 
 * HTTP fetch and populates its in-memory strategy engine.
 * Any call to isEnabled() before this promise resolves would silently return false.
 */
export async function initUnleash(): Promise<void> {
  unleashInstance = await startUnleash({
    url: process.env.UNLEASH_API_URL || 'https://your-unleash-instance.com/api/',
    appName: 'checkout-service',
    customHeaders: {
      Authorization: process.env.UNLEASH_CLIENT_TOKEN || 'your-client-token',
    },
  });

  console.log('✅ Unleash SDK synchronized and ready for in-memory evaluations.');
}

interface UserContext {
  userId: string;
  email: string;
  country: string;
}

export function getCheckoutButtonConfig(user: UserContext) {
  // Construct context object needed by Unleash evaluation engine:
  // - userId: used by MurmurHash for consistent, sticky 50% gradual rollout
  // - properties.country: matched against the "country === US" constraint
  const context = {
    userId: user.userId,
    properties: {
      country: user.country,
      email: user.email,
    },
  };

  const FLAG_NAME = 'checkout-button-experiment';

  // Check if user qualifies (Gradual Rollout 50% AND country === 'US')
  const isQualified = unleashInstance.isEnabled(FLAG_NAME, context);

  if (!isQualified) {
    // Non-qualifying users (e.g. Non-US users or users outside the 50% rollout bucket)
    return {
      buttonColor: 'blue',
      buttonText: 'Pay Now (Legacy)',
      isExperimentParticipant: false,
    };
  }

  // For qualified users, get their assigned variant
  const variant = unleashInstance.getVariant(FLAG_NAME, context);

  switch (variant.name) {
    case 'variant-a':
    case 'red-button':
      return {
        buttonColor: 'red',
        buttonText: 'Pay Now (Variant A)',
        isExperimentParticipant: true,
      };

    case 'variant-b':
    case 'green-button':
      return {
        buttonColor: 'green',
        buttonText: 'Complete Order (Variant B)',
        isExperimentParticipant: true,
      };

    default:
      // Safety fallback in case variant definitions are missing
      return {
        buttonColor: 'blue',
        buttonText: 'Pay Now',
        isExperimentParticipant: false,
      };
  }
}

const app = express();

async function bootstrap() {
  try {
    // ALWAYS await Unleash BEFORE calling app.listen()
    await initUnleash();

    app.get('/checkout', (req, res) => {
      const user: UserContext = {
        userId: (req.query.userId as string) || 'user-101',
        email: 'dev@company.com',
        country: (req.query.country as string) || 'US',
      };

      const buttonConfig = getCheckoutButtonConfig(user);
      res.json({ user, buttonConfig });
    });

    app.listen(3000, () => {
      console.log('🚀 Express server running on http://localhost:3000/checkout');
    });
  } catch (error) {
    console.error('Failed to initialize application:', error);
    process.exit(1);
  }
}

bootstrap();

💡 Note on Code Structure: This snippet is intentionally simplified to keep the Unleash evaluation flow easy to read.

⚠️ The Cold-Start Gotcha: If you use initialize() instead of await startUnleash(), the SDK fetches rules asynchronously in the background. Any request hitting isEnabled() before that first network fetch completes will silently evaluate to false.

Managing "Flag Debt"

The main trap with feature flags is leaving them in your codebase indefinitely. Dead flags clutter your code with obsolete branches and make testing difficult.

When creating a Release Toggle:

1. Create a corresponding cleanup task in your backlog at the same time.
2. Once a rollout reaches 100% and remains stable, delete the flag from your management server and remove the conditional if/else block from your codebase.

Conclusion

Feature flags turn high-risk deployments into low-risk, everyday events. By moving from manual environment checks to automated client SDK evaluation with tools like Unleash, software teams gain precise control over rollout speeds, targeted releases, and immediate safety rollbacks.

Whether you are trying to decouple deployments from business releases or perform canary rollouts, introducing feature toggles is one of the most effective upgrades you can bring to your modern software development lifecycle.

References & Further Reading

• Hodgson, Pete. "Feature Toggles (aka Feature Flags)", Martin Fowler's Blog (2017). martinfowler.com/articles/feature-toggles.html
• Unleash Documentation. "Unleash Concepts: Activation Strategies & Variants". docs.getunleash.io/concepts

---

As always, I may miss some points, so if you have any questions or suggestions, please feel free to share them with me. If you know a better approach, I’d love to hear about it. I’m always open to learning and improving my knowledge.

Stay humble and keep learning!