It's Friday afternoon, and your team just deployed a new payment processor (Stripe) to production. The new payment system looks promising, and you're excited to see how it performs compared to PayPal.

But then, the Slack messages start pouring in:

😱 "Payments are failing! Users can't complete purchases!"

💸 "We're losing revenue because of this!"

🚨 "Customer support is overwhelmed with complaints!"

📉 "Our conversion rate just dropped by 40%!"

Your heart sinks. The new payment processor you worked on for weeks is causing production issues, and you have no way to turn it off quickly. You're stuck with two terrible options:

1. 🔄 Rollback the entire deployment - This means losing all the other bug fixes and improvements that went out with this release
2. ⚡ Hotfix the issue - But this takes time, and meanwhile, your users are suffering and you're losing money

This is exactly the nightmare that happens when you deploy critical systems without any way to control them after deployment.

Feature flags (also known as feature toggles or feature switches) are a software development technique that allows you to enable or disable features in your application without changing the code.

Think of them as light switches for your code. You can turn features on and off quickly, and control when features are available to users.

At their core, feature flags are simple conditional statements in your code:

if (featureFlags.isEnabled("useStripePayment")) {
  // Use Stripe payment processor
  processPaymentWithStripe();
} else {
  // Use PayPal payment processor
  processPaymentWithPayPal();
}

Instead of having the feature permanently baked into your code, you wrap it in a conditional check. This gives you the power to:

• 🎯 Control feature visibility - Turn features on/off quickly
• 🧪 Test safely - Enable features for testing without affecting all users
• 🚀 Deploy with confidence - Ship code with features disabled, then enable them when ready
• 🔄 Rollback quickly - Turn off problematic features rapidly

There are many ways to implement feature flags in your application, ranging from simple environment variables to sophisticated external services. Each approach has its own trade-offs, and the "best" solution depends on your specific needs.

Before diving into implementation options, let's understand the different types of feature flags you might need:

The simplest type - a feature is either enabled or disabled for everyone.

// Simple true/false
const isStripePaymentEnabled = true;

Use cases: New payment processors, experimental functionality, maintenance modes.

Enable a feature for a specific percentage of users.

// Enable for 25% of users
const rolloutPercentage = 25;

Use cases: Gradual rollouts, A/B testing, risk mitigation.

Enable features based on user characteristics (e.g., user ID, role, region).

// Enable for users in specific regions
const userRegion = "US";
const isFeatureEnabled = userRegion === "US";

Use cases: Geographic rollouts, beta testing with specific users, premium payment methods.

There are several ways to implement feature flags, but we'll focus on the two most common approaches that cover the majority of use cases.

The most straightforward approach - using environment variables to control features.

Advantages:

• 🚀 Simple to implement - Just a few lines of code.
• 🏠 No external dependencies - Everything stays within your application's codebase.
• ⚡ Fast performance - No network calls needed.
• 🧠 Easy to understand - Clear and transparent.

Disadvantages:

• 🔄 Requires redeploy - Any change to a flag's value necessitates a new deployment and application restart.
• ⏰ No real-time updates - Changes are not instant; they become active only after a new deployment is live.
• 🎯 Limited dynamic targeting - Primarily suited for simple boolean flags. Implementing percentage-based or complex user-based flags requires custom logic and still needs a redeploy to modify the targeting criteria.

Perfect for: Small to medium teams, simple use cases, getting started with feature flags.

Using dedicated feature flag services like ConfigCat, LaunchDarkly, or Harness.

Advantages:

• ⚡ Real-time updates - Change flags instantly without redeployments.
• 🎯 Advanced targeting - Sophisticated user-based, percentage, and custom targeting rules even without changing code.
• 📊 Analytics and monitoring - Built-in tools to track feature usage and performance.
• 👥 Team collaboration - User interfaces allow non-developers to manage flags.
• 🧪 A/B testing - Comprehensive experimentation tools.
• 📝 Audit trails - Track who changed what and when.

Disadvantages:

• 🔗 External dependency - Relies on a third-party service, introducing a potential point of failure.
• 💰 Cost - Typically involves monthly subscription fees.
• 🧩 Complexity - More setup, configuration, and a steeper learning curve.
• 🌐 Network calls - Potential performance impact due to API calls to the flag service. While this can be mitigated with webhook systems that notify your app of changes, it requires a more complex setup.
• 🔒 Vendor lock-in - Can be challenging to switch providers later. While OpenFeature provides a vendor-agnostic standard to avoid code-level lock-in, few feature flag solutions have implemented it yet. Additionally, complex features like webhooks still require vendor-specific implementations.

Perfect for: Large teams, complex targeting needs, when you require real-time control, advanced experimentation, and robust collaboration features.

In this guide, we'll implement feature flags using environment variables. This might seem like the "simple" option, but it's actually the perfect starting point for most teams.

Here's why environment variables are often the right choice:

• 🎯 Solves 80% of use cases - Most feature flags are simple on/off switches.
• 🚀 Quick to implement - You can have feature flags working in minutes.
• 💰 Cost effective - No monthly fees or external dependencies.
• 🧠 Easy to understand - Your team can grasp it immediately.
• 🔧 Easy to debug - No network issues or external service problems.

Many successful companies start with environment variables and only move to external services when they hit specific limitations. There's nothing wrong with starting simple - in fact, it's often the smartest approach.

Let's see how to implement this in Node.js.

Environment variables are key-value pairs that are available to your application at runtime. They're perfect for configuration that changes between environments (development, staging, production) without modifying your code.

In Node.js, you can access environment variables through the process.env object:

// Access environment variables
const port = process.env.PORT || 3000;
const databaseUrl = process.env.DATABASE_URL;

The most common way to manage environment variables in Node.js is using a .env file. This file contains your configuration and is typically not committed to version control.

Create a .env file in your project root:

.env
# Server Configuration
PORT=3000
DATABASE_URL=postgresql://localhost:5432/myapp
NODE_ENV=development

# Feature Flags (FF)
FF_USE_STRIPE_PAYMENT=false
FF_USE_POSTGRESQL=true
FF_USE_SEND_GRID_EMAIL_CLIENT=true

First, we will need a way to load the env vars that we have in the .env.

There are many libraries to help with this, but one of the most popular and widely used is dotenv. It allows you to load environment variables from a .env file into process.env.

To install dotenv, run the following command in your project directory:

npm install dotenv --save

Now let's create a dedicated feature flags configuration that reads from environment variables:

src/config/feature-flags.ts
import 'dotenv/config' // Load environment variables from .env file

interface FeatureFlags {
  /**
   * Controls whether to use Stripe instead of PayPal for payments
   * Owner: @payments-team
   * Created: 2024-01-15
   * Expected removal: 2024-03-01
   */
  useStripePayment: boolean;

  /**
   * Enables SendGrid email client instead of the default SMTP client
   * Owner: @backend-team
   * Created: 2024-01-10
   * Expected removal: 2024-02-15
   */
  useSendGridEmailClient: boolean;
}

// Helper function to parse boolean environment variables
const parseBoolean = (value: string | undefined, defaultValue: boolean = false): boolean => {
  if (value === undefined) return defaultValue;
  return value.toLowerCase() === 'true';
};

// Create feature flags configuration
export const featureFlags: FeatureFlags = {
  useStripePayment: parseBoolean(process.env.FF_USE_STRIPE_PAYMENT, false),
  useSendGridEmailClient: parseBoolean(process.env.FF_USE_SEND_GRID_EMAIL_CLIENT, false),
};

// Helper function to check if a feature is enabled
export const isFeatureEnabled = (featureName: keyof FeatureFlags): boolean => {
  return featureFlags[featureName];
};

Now that we have our feature flags configuration set up, let's see how to use them in your Node.js application with a simple, practical example.

Let's say you're building a payment processing system. You want to test a new payment processor (Stripe) while keeping the old one (PayPal) as a fallback.

Here's how you can implement this with feature flags:

src/routes/payment.ts
import { isFeatureEnabled } from '../config/feature-flags';
import { StripeProcessor } from '../services/stripe-processor';
import { PayPalProcessor } from '../services/paypal-processor';

app.post('/api/payment', async (req, res) => {
  try {
    const { amount, currency, customerId } = req.body;

    if (isFeatureEnabled('useStripePayment')) {
      // Use new Stripe payment processor
      const stripeProcessor = new StripeProcessor();
      const payment = await stripeProcessor.processPayment({
        amount,
        currency,
        customerId,
        paymentMethod: 'card'
      });

      res.json({
        success: true,
        paymentId: payment.id,
        processor: 'stripe',
        status: payment.status
      });
    } else {
      // Use legacy PayPal payment processor
      const paypalProcessor = new PayPalProcessor();
      const payment = await paypalProcessor.createPayment({
        amount,
        currency,
        customerId,
        method: 'paypal'
      });

      res.json({
        success: true,
        paymentId: payment.paymentId,
        processor: 'paypal',
        status: payment.status
      });
    }
  } catch (error) {
    res.status(500).json({
      error: 'Payment processing failed',
      processor: isFeatureEnabled('useStripePayment') ? 'stripe' : 'paypal'
    });
  }
});

In this case, we are directly calling isFeatureEnabled() and this is pretty straightforward. However, for more complex applications or when you want to reduce coupling, other strategies can be more beneficial and you can combine it with patterns like Dependency Injection (DI) where we can select what instance to provide to the class depending on some flag.

Now that you understand how to implement feature flags, let's cover some best practices to make your feature flag system robust and maintainable.

Use clear, descriptive names. We can even prefix them with FF_ or some other convention to indicate they are flags helping to avoid confusion between regular configuration variables and feature flags.

// ✅ Good naming
FF_USE_STRIPE_PAYMENT = true;
FF_USE_SEND_GRID_EMAIL_CLIENT = true;

// ❌ Avoid unclear names
FEATURE_NEW_THING = true;
FEATURE_TEST = false;

Also, try to use always the same naming for the same flags, for example, if you have useStripePayment always use useStripePayment instead of sometimes using isStripePaymentEnabled or isStripeActive. This will help you to avoid confusion and make easier to search for the flags in your codebase, really important to clean up the flags when they are no longer needed.

Always document your feature flags and assign clear ownership, to know who is responsible for each flag. This helps with:

• 🧠 Understanding purpose - Why the flag exists and what it controls.
• 👑 Tracking changes - Who can enable/disable the flag.
• 🧹 Lifecycle management - When the flag should be removed.
• 📊 Monitoring - Who is responsible for monitoring the feature's performance.

Always provide a sensible default value for your feature flags, especially if the environment variable is missing. This prevents unexpected behavior if a flag isn't set.

Fail Safe: For critical features, consider defaulting to the "off" state (false) to prevent accidental exposure or issues.

• 🤓 Test Both States: Test your application with the feature flag both ON and OFF.
• ✅ Unit and Integration Tests: Write tests that explicitly set flag values to ensure all code paths are covered.
• 🏄‍♀️ End-to-End (E2E) Tests: Include E2E tests that simulate user flows with different flag configurations.

• 🗄️ Centralized Flag Access: Ensure all flag checks go through a single, well-defined module (e.g., src/config/feature-flags.ts). This makes it easy to inspect or mock flag values.
• 🔎 Logging: Log which features are enabled/disabled at application startup or when a flag is accessed, especially in non-production environments.
• 🫀 Health Checks/Info Endpoints: Consider adding an endpoint (e.g., /api/flags) that exposes the current state of all active feature flags (carefully, without sensitive info, and ideally protected in production).
• 🧐 Monitoring: If using external services, leverage their built-in monitoring. For environment variables, ensure your application logs are sufficient to understand flag states.

Flags Are Temporary: Most feature flags are not meant to live forever. They should have a defined lifecycle:

1. 🆕 Creation: Introduce the flag for a new feature or experiment.
2. 🎢 Rollout: Gradually enable the feature (if applicable).
3. 🧘 Stabilization: The feature is fully released and stable.
4. 🧹 Cleanup: Remove the flag and the old code path. This is critical to prevent "flag debt" and code complexity.

• 🌱 Start Coarse, Refine if Needed: Begin with broader flags (e.g., FF_USE_NEW_CHECKOUT_FLOW). If you later need to control smaller parts of that flow independently, you can introduce more granular flags.
• 😖 Avoid Too Many Flags: An excessive number of flags can lead to "flag fatigue" and make your codebase harder to understand and manage.

• 📡 Server-Side Flags for Sensitive Logic: For flags controlling critical business logic, sensitive data, or security features, ensure they are only evaluated on the server-side.
• 👤 Client-Side Exposure (with caution): If you need to expose a flag to the client (e.g., for UI toggles), ensure no sensitive information is leaked. For raw environment variables, you'd typically need to expose them via an API endpoint or a build-time process that only includes non-sensitive flags.
• 🔏 Never Trust Client-Side Flags: Always re-validate critical decisions on the server, even if a client-side flag suggests a feature is enabled.

Following these best practices will help you build a robust and maintainable feature flag system that scales with your application.

Feature flags are not just a technical tool — they’re a strategic safety net for modern software development.

Starting with environment variables is often the smartest move: simple, cost-effective, and enough for most use cases.

The key is to treat feature flags seriously. Name them clearly, document ownership and purpose, provide safe defaults, and clean them up when they’re no longer needed.

A well-managed feature flag system gives you control, reduces risk, and makes deployments a lot less stressful.

Now, go forth and ship with confidence!