Node.js Feature Flag Kill Switch Implementation

This guide shows you how to add a kill switch to your Node.js feature flags, allowing you to instantly disable a feature in production without redeploying. You’ll learn to implement a simple, centralized kill switch using environment variables and a configuration file, plus how to integrate it with popular feature flag libraries. This is essential for quickly mitigating issues caused by buggy releases.

What You’ll Need

• A Node.js project (any version 12 or higher)
• Basic familiarity with environment variables and JSON
• Optional: a feature flag library like flags, unleash-client, or launchdarkly-node-server-sdk if you’re using one

Step-by-Step

1. Create a central configuration module. Make a file like config.js that exports a function to read your feature flags. This will be the single source of truth for all flag states.
2. Define your flags with a default state. In the config module, create an object that lists each feature flag and its default value (true/false). For example: { newCheckout: true, betaDashboard: false }.
3. Add a global kill switch. Add a killSwitch property to your flags object. When this is true, all features are considered off. Set its default to false.
4. Read overrides from environment variables. Use process.env to allow overriding any flag at runtime. For each flag, check if an environment variable with the same name (in uppercase) exists. If it does, parse it as a boolean and use that value.
5. Implement a kill switch check. In your config module, export a function isFeatureEnabled(flagName) that returns false if the kill switch is on, otherwise returns the flag’s value.
6. Use the kill switch in your code. Replace direct flag checks with calls to isFeatureEnabled('flagName'). For example: if (isFeatureEnabled('newCheckout')) { ... }.
7. Test locally. Run your app with KILL_SWITCH=true node server.js and verify all features are disabled. Also test with individual flag overrides like NEW_CHECKOUT=false.
8. Integrate with a feature flag library (optional). If you use a library like Unleash or LaunchDarkly, you can still use a kill switch. Most libraries allow you to set a fallback function. Create a wrapper that checks your kill switch first, then calls the library’s evaluation method.
9. Deploy and activate. Deploy your code with the kill switch defaulting to false. When you need to disable a feature, set the environment variable KILL_SWITCH=true on your server (or use your hosting provider’s console) and restart the process.

Common Mistakes

• Forgetting to parse environment variables. Environment variables are strings. If you set NEW_CHECKOUT=false, the string 'false' is truthy. Always parse: process.env.NEW_CHECKOUT === 'true'.
• Hardcoding flags in multiple places. If you check flags directly in many files, you’ll miss some when adding a kill switch. Centralize all flag checks in one module.
• Not considering caching. If you cache flag values, a kill switch change won’t take effect until the cache expires. Make sure your kill switch check is not cached, or clear the cache when the kill switch is toggled.
• Kill switch only in one environment. You need the kill switch in every environment (dev, staging, prod) to test it properly. Deploy the same code everywhere.

Tips

• Use a library for complex needs. If you need gradual rollouts, user targeting, or A/B testing, consider a full feature flag service. Your kill switch can still be a top-level override.
• Log when the kill switch is on. Add a log message when the kill switch is active so you know why features are disabled.
• Make the kill switch name consistent. Use KILL_SWITCH or FEATURE_KILL_SWITCH across all your projects to avoid confusion.
• Consider a file-based kill switch. Instead of environment variables, you can read a JSON file that can be edited without restarting. This is useful if your host doesn’t allow env var changes without redeploy.

Troubleshooting

• Feature still enabled after setting kill switch. Check that the environment variable is actually set and that your code reads process.env.KILL_SWITCH correctly. Also ensure you restart the Node process after changing env vars.
• Boolean parsing issues. If you use Boolean(process.env.FLAG), it will always be true for any non-empty string. Use === 'true' or a helper function.
• Kill switch not working with a library. If you’re using a library, make sure your wrapper actually calls isFeatureEnabled from your config, not the library’s method directly. Double-check the library’s fallback API.
• Changes not reflected after restart. Some hosting platforms cache env vars. Check your platform’s documentation on how to force a fresh deployment.

Frequently Asked Questions

Can I use a kill switch without a feature flag library?

Yes, the environment variable approach works standalone. It’s simple and effective for small projects.

How do I toggle a kill switch in production?

Set the environment variable on your server (e.g., KILL_SWITCH=true) and restart the Node process. Most platforms allow this via a console or CLI.

Is a kill switch the same as a feature flag?

No. A feature flag controls a specific feature. A kill switch is a global emergency brake that disables all features at once.

What if I have multiple kill switches for different feature groups?

You can add more granular switches like KILL_SWITCH_PAYMENT and KILL_SWITCH_UI. Just check them in your config logic.

Can I use a kill switch with a database-backed flag system?

Yes, but the kill switch should be checked before hitting the database. That way it works even if the database is down.

How do I test the kill switch without affecting users?

Deploy to a staging environment first, set the kill switch, and verify all features are disabled. Then promote to production.

Related

• Motion Tracking Sensor Buying Guide
• AI Self-Regulation: Can Voluntary Pledges Protect Frontier Systems?
• GTA 6 vs GTA 5: Open World Changes