Transform scattered notes into a polished knowledge base article

# How to Set Up and Manage Feature Flags in Our Stack **Summary:** This guide covers how to create, configure, test, and retire feature flags using our LaunchDarkly setup. Covers both frontend and backend flags with rollout strategies. **Last updated:** June 2024 | **Owner:** Platform Team | **Audience:** All engineers --- ## Table of Contents 1. [Overview](#overview) 2. [When to Use Feature Flags](#when-to-use) 3. [Creating a New Flag](#creating) 4. [Frontend Flag Integration](#frontend) 5. [Backend Flag Integration](#backend) 6. [Rollout Strategies](#rollout) 7. [Testing Flags Locally](#testing) 8. [Monitoring Flag Impact](#monitoring) 9. [Retiring Flags](#retiring) 10. [Troubleshooting](#troubleshooting) --- ## Overview We use LaunchDarkly for feature flags across all services. Every new feature that touches production should be behind a flag. No exceptions for user-facing changes. **Key concepts:** - **Flag key:** Kebab-case identifier (e.g., `new-checkout-flow`). Once created, it cannot be renamed. - **Variations:** The possible values a flag can return. Boolean flags have `true`/`false`. Multivariate flags can return strings, numbers, or JSON. - **Targeting rules:** Conditions that determine which variation a user gets. Can target by user ID, email domain, plan tier, percentage, or custom attributes. - **Environments:** We have four: `local`, `staging`, `production-canary`, `production`. Flags are configured independently per environment. --- ## When to Use Feature Flags | Use Case | Flag Type | Example | |---|---|---| | Gradual rollout of new feature | Boolean | `new-dashboard-v2` | | A/B testing | Multivariate (string) | `pricing-page-variant` → "control", "variant-a", "variant-b" | | Kill switch for unstable feature | Boolean | `enable-real-time-sync` | | Ops toggle (no deploy needed) | Boolean | `enable-email-notifications` | | Entitlement gating | Boolean with targeting | `enterprise-analytics` (on for enterprise plan users) | > **⚠️ Warning:** Do NOT use feature flags for configuration that changes frequently (e.g., rate limits, copy text). Use environment variables or a config service for those. --- ## Creating a New Flag ### Step 1: Choose a naming convention ``` Format: {scope}-{feature-name} Examples: checkout-one-click-buy dashboard-activity-feed api-v3-pagination ``` ### Step 2: Create in LaunchDarkly 1. Go to LaunchDarkly → Flags → "Create flag" 2. Fill in: - **Name:** Human-readable (e.g., "One-Click Checkout") - **Key:** Kebab-case (e.g., `checkout-one-click-buy`) - **Tags:** Add team tag (e.g., `team-growth`, `team-platform`) - **Type:** Boolean for most cases 3. Set default values: - **Variation when on:** `true` - **Variation when off:** `false` - **Default "off" in all environments** — flags should be explicitly enabled ### Step 3: Document the flag Add a description in LaunchDarkly with: - What the flag controls - Link to the Linear ticket or RFC - Expected retirement date - Owner (who to ask about this flag) > **💡 Tip:** Set a "maintainer" in LaunchDarkly. This person gets notified if the flag has been on for 90+ days without being cleaned up. --- ## Frontend Flag Integration We use the LaunchDarkly React SDK. The provider is already set up in `app/providers.tsx`. ### Checking a flag in a component: ```typescript import { useFeatureFlag } from '@/hooks/useFeatureFlag'; function CheckoutPage() { const showOneClickBuy = useFeatureFlag('checkout-one-click-buy', false); return ( <div> {showOneClickBuy && <OneClickBuyButton />} <StandardCheckout /> </div> ); } ``` ### Server-side flag check (Next.js): ```typescript import { getServerFlag } from '@/lib/feature-flags'; export default async function Page() { const showNewDashboard = await getServerFlag('dashboard-v2', false); // ... } ``` > **⚠️ Warning:** Never use `useFeatureFlag` in a server component. Use `getServerFlag` instead. The React hook requires client-side context. --- ## Backend Flag Integration We use the LaunchDarkly Node SDK. The client is initialized in `src/lib/launchdarkly.ts`. ```typescript import { flagClient } from '@/lib/launchdarkly'; async function processOrder(userId: string) { const useNewPipeline = await flagClient.boolVariation( 'orders-new-pipeline', { key: userId }, false // default if flag evaluation fails ); if (useNewPipeline) { return newOrderPipeline(userId); } return legacyOrderPipeline(userId); } ``` > **💡 Tip:** Always pass the user context (`{ key: userId }`) so targeting rules work correctly. Anonymous users should use a session ID as the key. --- ## Rollout Strategies ### Strategy 1: Internal → Canary → Full (recommended for most features) 1. Enable for internal users only (target by email domain `@ourcompany.com`) 2. After 2-3 days: Enable in `production-canary` (5% of traffic) 3. Monitor for 24-48 hours — check error rates, latency, user feedback 4. Ramp to 25% → 50% → 100% over 3-5 days ### Strategy 2: Beta Opt-In (for features users need to learn) 1. Create a `beta-features` page in settings 2. Users toggle the flag for themselves (via our beta API) 3. Collect feedback via in-app survey 4. When ready: enable for everyone and remove the opt-in ### Strategy 3: Kill Switch (for risky changes) 1. Deploy code with flag defaulting to OFF 2. Enable in production with a single toggle when ready 3. If something breaks: turn off immediately — no deploy needed 4. Fix the issue, re-enable --- ## Testing Flags Locally Set flag overrides in `.env.local`: ```bash # Force flag values for local development FEATURE_FLAG_OVERRIDE_checkout-one-click-buy=true FEATURE_FLAG_OVERRIDE_dashboard-v2=false ``` Or use the LaunchDarkly debugger in the browser (extension available for Chrome). --- ## Monitoring Flag Impact After enabling a flag, monitor these for 48 hours: - **Error rate:** Check Datadog for any spike in errors correlated with the flag - **Latency:** Compare p50/p99 latency for users with flag on vs. off - **Business metrics:** Conversion rate, engagement, etc. (check Amplitude) Set up a Datadog dashboard that segments by flag variation. Template: [Feature Flag Monitoring Template]. --- ## Retiring Flags Flags must be retired when: - Feature is fully rolled out to 100% of users for 2+ weeks - Feature was abandoned and code is being removed ### Retirement checklist: - [ ] Confirm flag is at 100% for 2+ weeks (or 0% if abandoned) - [ ] Remove flag checks from code (search codebase for the flag key) - [ ] Remove the "off" code path if the feature is permanent - [ ] Archive the flag in LaunchDarkly (don't delete — archive preserves history) - [ ] Open a cleanup PR and link it to the original feature ticket > **⚠️ Warning:** Our codebase currently has 47 stale flags. Don't add to the problem. Set a calendar reminder for flag retirement when you create the flag. --- ## Troubleshooting **Flag is returning the default value unexpectedly** - Check that the flag is enabled in the correct environment - Verify the user context key matches what targeting rules expect - Look at the LaunchDarkly flag evaluation log (Debugger tab) **Flag works locally but not in staging** - Local overrides in `.env.local` don't apply to staging. Check the flag config in the staging environment in LaunchDarkly. **Flag changes aren't reflecting immediately** - Frontend: The SDK polls every 30 seconds by default. For instant updates, enable streaming (already on in production, off in local). - Backend: The Node SDK uses streaming by default. If it's not updating, check the SDK connection status in logs. **I accidentally turned off a flag in production** - Turn it back on immediately via LaunchDarkly (no deploy needed) - Check the audit log to see who changed it and when - Post in #incidents if it affected users --- ## Related Articles - [How to Run A/B Tests with Feature Flags](/kb/ab-testing-guide) - [Incident Response: Using Kill Switches](/kb/incident-kill-switches) - [LaunchDarkly Admin Access Request](/kb/ld-access-request)