Forem: Flaggy

How to use feature flags in JavaScript and TypeScript

Flaggy — Wed, 20 May 2026 02:17:00 +0000

A practical guide to implementing feature flags in JS/TS: what they are, when to use them, and how to avoid the traps that make them painful to manage.

Feature flags are a conditional: if (flagEnabled) { show new thing } else { show old thing }. That’s the entire concept. The value comes from where the condition is evaluated and who controls it — not the developer at deploy time, but a dashboard at runtime.

This guide covers the core patterns, when each one applies, and what separates a well-managed flag from one that quietly rots in your codebase.

The basic pattern

A feature flag SDK gives you a function. You call it with a flag key, optionally a user context, and it returns a boolean (or a variant, for multivariate flags).

import { flaggy } from '@flaggy.io/sdk-js';

const client = flaggy({ apiKey: process.env.FLAGGY_API_KEY });
await client.initialize();

if (client.isEnabled('release-checkout-flow', { key: user.id })) {
  return <NewCheckout />;
}
return <LegacyCheckout />;

The SDK downloads your ruleset on initialization and evaluates locally. No network call happens at the point of evaluation — it’s a dictionary lookup against rules in memory. This is why MAU-based pricing from some vendors doesn’t make technical sense: the vendor’s infrastructure isn’t involved when a flag evaluates.

When to use a feature flag

Release control is the most common case. You merge a half-finished feature to main behind a flag, deploy continuously, and flip the flag when it’s ready. No long-lived feature branches, no merge conflicts.

Percentage rollouts let you ship to 5% of users, watch your error rate, and expand if it looks clean. This is a canary deployment without the infrastructure complexity of actually routing traffic.

User targeting lets you ship to internal users, beta testers, or a specific customer segment first. You define a segment in the dashboard — “users where plan = enterprise” — and enable the flag for that segment.

Kill switches are flags you never intend to remove. A circuit breaker on a third-party integration, a way to disable a feature if it’s causing support volume. Having this in a dashboard is faster than a deploy.

The initialization pattern

Initialize the SDK once at app startup and share the client. Don’t initialize per-request or per-component — it defeats the local evaluation model.

// flaggy.ts — initialize once, export everywhere
import { flaggy } from '@flaggy.io/sdk-js';

export const flags = flaggy({
  apiKey: process.env.FLAGGY_API_KEY!,
});

await flags.initialize();
// any component or module
import { flags } from './flaggy';

const showFeature = flags.isEnabled('my-feature', { key: currentUser.id });

Targeting rules

Most SDKs let you pass a context object — any key/value pairs you want to use for targeting. The dashboard lets you define rules against those attributes without a code change.

Common context attributes:

flags.isEnabled('experiment-dark-mode', {
  key: user.id,
  email: user.email,
  plan: user.plan,           // target by billing tier
  accountAge: daysSinceSignup,
  country: user.countryCode,
});

You define the rule once in the dashboard: “users where plan = team AND accountAge > 30”. No deploy required to change targeting.

The cleanup problem

The real cost of feature flags isn’t evaluating them — it’s the ones you forget to remove. A codebase with 200 permanent flags is harder to reason about than one with 20.

A few habits that help:

Add a ticket at flag creation. When you create a flag, immediately create a ticket to remove it after the rollout is done. The flag has a lifespan of “rollout + one release cycle.”

Name flags by lifecycle prefix. Use a prefix that encodes intent: release-new-dashboard, experiment-checkout-button, kill-switch-payment-provider, ops-cache-ttl. It makes lifespan visible at a glance — you can immediately separate flags that need cleanup from ones that are permanent.

Review old flags quarterly. Pull a list of flags that haven’t changed in 90 days. Most of them are either fully rolled out (safe to remove) or forgotten experiments.

Server-side vs client-side evaluation

Some teams evaluate flags server-side to avoid any flag state being visible in the client bundle. The tradeoff:

Client-side: zero latency at evaluation, no server dependency, flag rules are technically visible in the bundle (usually fine for most use cases)
Server-side: rules stay private, adds one lookup per request (fast if in-memory, latency concern if remote)
For most product flags — rollouts, A/B tests, kill switches — client-side evaluation is fine. For flags that gate access control or pricing, server-side is worth the overhead.

What to look for in a flag platform

You need: a dashboard to manage flags without a code change, targeting rules, audit history (who changed what and when), and an SDK that evaluates locally.

What you don’t need to pay for: MAU metering. Modern SDKs evaluate client-side. The vendor’s servers aren’t involved in evaluations — if you’re paying per-MAU, you’re paying for a proxy metric that doesn’t reflect actual vendor cost.

Flaggy’s Team plan is $99/month flat — unlimited seats, no MAU fees, full flag analytics and audit log included.

Feature flag best practices for engineering teams

Flaggy — Tue, 19 May 2026 04:40:00 +0000

The patterns that make feature flags useful long-term, and the habits that keep them from becoming a maintenance burden. Drawn from common failure modes.

Feature flags are simple in concept. The failure modes are also simple, and predictable. Most teams hit the same three problems: flags that never get cleaned up, targeting rules nobody understands, and flag state that’s invisible to the people who need it.

Here are the practices that prevent each of those.

Name flags by intent, not implementation

A flag named “New dashboard v2” tells you what it wraps but not why it exists or when it ends. A flag named “Release dashboard redesign” communicates both that it’s temporary and what it controls.

A useful naming convention uses a prefix word to encode the flag’s lifecycle. In Flaggy, names are entered as plain text and the key is generated automatically — “Release dashboard redesign” becomes the key release-dashboard-redesign in your code.

Useful prefixes:

Release — enables a new feature during a gradual release. Intended to be removed once fully shipped. e.g. “Release dashboard redesign”
Experiment — an A/B test. Has a defined end date. e.g. “Experiment checkout button color”
Kill switch — a permanent circuit breaker. Not expected to be removed. e.g. “Kill switch payments integration”
Ops — a configuration flag for operational tuning. May be permanent. e.g. “Ops cache TTL override”

The prefix communicates lifespan at a glance. When you’re reviewing a list of 50 flags, you can immediately separate the ones that should be cleaned up from the ones that are load-bearing.

Create the cleanup ticket at flag creation

The most reliable way to remove a flag is to plan for it before you merge. When you create a flag in the dashboard, immediately create a ticket in your issue tracker: “Remove flag rollout-feature-name after full rollout.”

Without this step, the flag gets created with full intention to clean it up, but the rollout ends, the team moves on, and the ticket never gets written. Flags accumulate. After a year you have 150 flags and nobody knows which ones are active.

The sequence is: create flag → create cleanup ticket → merge code → run rollout → remove flag → close ticket.

Set flag context consistently

The user context you pass to the SDK determines what targeting rules you can write. If different parts of the app pass different context attributes, you end up with targeting rules that silently don’t apply everywhere.

Define a canonical context object and build it in one place:

function buildFlagContext(user: User): FlagContext {
  return {
    key: user.id,
    email: user.email,
    plan: user.subscriptionPlan,
    teamId: user.teamId,
    accountAgeDays: differenceInDays(new Date(), user.createdAt),
    country: user.countryCode,
  };
}

Use this everywhere. When you add a new attribute, add it here and it becomes available for targeting across the entire app.

Keep flag logic at the boundary, not deep in components

Flag checks embedded deep in component trees or utility functions are hard to find and easy to forget. Prefer pushing flag evaluation to the boundary of a feature — the entry point that decides which version to render.

Harder to clean up:

// buried in a utility function
function formatPrice(amount: number) {
  if (flags.isEnabled('new-pricing-display')) {
    return newFormat(amount);
  }
  return legacyFormat(amount);
}

Easier to clean up:

// at the component boundary
function PricingSection({ user }) {
  const useNewDisplay = flags.isEnabled('new-pricing-display', { key: user.id });
  return useNewDisplay ? <NewPricingDisplay /> : <LegacyPricingDisplay />;
}

The second version makes the flag visible at a high level. When you remove it, you delete the condition and the LegacyPricingDisplay import — the diff is obvious.

Use segments for reusable targeting logic

If you find yourself writing the same targeting rule on multiple flags — “users where plan = team AND accountAge > 30 days” — define it as a segment once and target the segment.

Benefits:

Rules are consistent. If your definition of “beta users” changes, you update it in one place.
Auditing is easier. You can see which flags target a segment.
Onboarding new team members is simpler — they see named segments, not repeated rule logic.
Segments with clear names also make flag state legible to non-engineers. “This flag is enabled for the Beta Users segment” is understandable to a PM in a way that a list of attribute conditions isn’t.

Make flag state visible to the right people

The support engineer who gets a ticket about a broken feature needs to check flag state. The PM managing a rollout wants to see current coverage. The on-call engineer debugging an incident needs to know which flags are currently active.

This is the hidden argument for unlimited seats: restricting dashboard access to the engineers who created the flags means everyone else is guessing. “Is this behind a flag?” becomes a Slack thread instead of a 30-second dashboard check.

Every person who touches your product in some capacity — PM, design, support, on-call — should be able to read flag state without asking an engineer.

Test the off state

When you add a flag, write a test for both branches — not just the new behavior you’re building.

describe('checkout flow', () => {
  it('shows new flow when flag is enabled', () => {
    mockFlag('new-checkout-flow', true);
    // ...
  });

  it('shows legacy flow when flag is disabled', () => {
    mockFlag('new-checkout-flow', false);
    // ...
  });
});

The off state breaks silently. The old code path doesn’t get touched during development, gets skipped in manual testing, and only fails in production when a flag gets rolled back. Test both.

Define a rollout pace

“We’ll do a gradual rollout” is not a plan. Before you flip the flag, decide:

What percentage you’ll start at (common: 1–5%)
What metric signals it’s safe to expand (error rate, p99 latency, specific event count)
How long you’ll hold at each stage before expanding
What triggers a rollback
Write this down somewhere. It doesn’t need to be formal — a comment in the cleanup ticket is enough. The goal is that whoever is on-call at 2am knows the answer to “is this flag supposed to be at 10%?” without having to find the person who created it.

Audit logs are not optional

You will have a production incident caused by a flag change. Someone will toggle something at the wrong time, or a targeting rule will match more users than expected, or the SDK will behave differently on an edge case.

When that happens, the first question is: what changed, when, and who changed it? An audit log that captures every flag toggle, rule edit, and segment update is how you answer that in minutes instead of hours.

This is not a nice-to-have — it’s incident response infrastructure. Flaggy includes audit logging on all plans, including the Free tier (7-day retention). The Team plan extends this to 90 days — worth considering if your incident review windows run longer.

If you're looking for a feature flag tool built around these practices — with automatic key generation from plain-text names, flag lifecycle visibility, and a clean dashboard — check out Flaggy.

Feature flag rollouts: canary-style risk reduction without the infrastructure

Flaggy — Mon, 18 May 2026 11:22:03 +0000

Canary deployments and feature flag rollouts solve the same problem at different layers. Here's how they actually work, when to use each, and how to combine them.

A canary deployment releases a new version of your application to a small slice of users before rolling it out fully. If something breaks, you catch it at 5% of traffic instead of 100%.

Feature flags solve the same problem at a different layer. Understanding the distinction helps you pick the right tool — and combine them when it makes sense.

How traditional canary deployments work

A canary deployment means running two versions of your application simultaneously in production. Version A is your current stable release. Version B is the new version. A routing layer — a load balancer, a service mesh, or your orchestration platform — directs a percentage of traffic to version B while the rest continues to hit version A.

In Kubernetes, the most common implementation uses two Deployments sharing a single Service selector. The Service routes traffic across all matching pods, so the traffic split is determined by the ratio of replicas:

# stable: 9 replicas
# canary: 1 replica
# → roughly 90% / 10% split

More sophisticated setups use an ingress controller (like NGINX or Traefik) or a service mesh (like Istio or Linkerd) to control the split with explicit weights, independent of replica count. This gives you precise percentages without scaling your fleet.

The key point: a canary deployment is an infrastructure strategy. Both versions of your code are running in production. The routing layer decides which users hit which version.

How feature flag rollouts work

A feature flag rollout is an application-layer strategy. You deploy a single version of your application to all servers. Inside that code, a flag evaluation controls which code path executes for a given user.

import { flaggy } from '@flaggy.io/sdk-js';

const client = flaggy({ apiKey: process.env.FLAGGY_API_KEY });
await client.initialize();

const useNewAlgorithm = client.isEnabled('new-recommendation-engine', {
  key: currentUser.id,
});

const results = useNewAlgorithm
  ? newRecommendationEngine(user)
  : legacyRecommendationEngine(user);

The key field ensures the same user always gets a consistent experience — the percentage is applied by hashing the key, not by random chance per request.

The key point: a feature flag rollout is a code strategy. One binary is deployed. The flag determines which behavior that binary exhibits for each user.

The difference in practice

Both approaches answer the same question: is this change safe at scale before committing fully? But they operate at different layers and have different strengths.

Canary deployments are managed by infrastructure or DevOps teams. Rollback means shifting traffic back to the stable version and eventually tearing down the canary — it’s a deployment operation. All changes in the new version are rolled back together; you can’t independently revert one feature if it shares a deployment with others.

Feature flag rollouts are managed by the team shipping the feature. Rollback means flipping a flag — it takes seconds and requires no deployment. Each feature has its own flag, so you can roll back one independently without touching anything else in the same release.

Another difference: canary deployments work at the traffic level, not the user level. You can route based on headers, cookies, or geographic region — but you’re routing requests, not targeting specific users. Feature flags can target individual users, user attributes, cohorts, or segments. You can enable a feature for your beta group specifically, then expand to a percentage of everyone else.

Percentage rollouts with Flaggy

The basic pattern is a flag with a percentage rollout rule. Start at 5%, verify your metrics look clean, expand in stages.

Monitoring during rollout

Before you expand, you need something to watch:

Error rates. Instrument both code paths with error tracking. An increase in exceptions for users in the new path is the clearest signal something is wrong.

try {
  const results = useNewAlgorithm
    ? newRecommendationEngine(user)
    : legacyRecommendationEngine(user);
  return results;
} catch (err) {
  errorTracker.capture(err, {
    tags: { flagVariant: useNewAlgorithm ? 'new' : 'legacy' }
  });
  throw err;
}

Latency. New code paths are often slower. Tag your performance measurements with the flag variant so you can compare p50/p99 between the two groups.

Business metrics. For user-facing features, watch the metrics that matter for the feature itself — conversion rate, click-through rate, session length. These take longer to accumulate signal but catch subtler problems that error rates miss.

Flag evaluation split. Flaggy’s analytics show the true/false breakdown for each flag in real time. If you set a 10% rollout and the split reads 0% or 100%, something is wrong before your error tracker has had time to accumulate signal.

The rollout ladder

A sensible default for most features:

You can compress this for low-risk changes or extend it for changes with high blast radius. The goal is giving each stage enough time to accumulate error budget signal, not following the ladder for its own sake.

Write the ladder down before you start. On-call engineers shouldn’t have to find the person who created the flag to know whether 25% coverage is expected or a bug.

Staged rollouts: internal team first

Percentage rollouts distribute randomly across your user base. For higher-risk changes, you want more control over who gets the new behavior first.

The pattern: enable the flag for internal users or beta testers before opening any percentage rollout. If something breaks, your team finds it — not your customers.

In Flaggy:

Create a segment: "users where email ends with @yourcompany.com"
Enable the flag for that segment — your team gets the new behavior
Run it internally for a few days, file bugs, fix them
Then start the percentage rollout for the broader user base
You can stack these rules: the flag is on for the internal segment and for 5% of everyone else. The two targeting rules work independently.

The Free plan includes 2 segments — enough for an internal team and a beta group. The Team plan has unlimited segments.

When to use infrastructure canary deployments instead

Feature flag rollouts handle application-level changes well. There are cases where you need infrastructure-level canaries:

Database schema migrations. Running two versions of your app simultaneously lets you verify the new schema is compatible before fully migrating. A flag can’t help if the migration breaks the old code path.

Dependency and runtime upgrades. Upgrading a major version of a core library, or moving to a new runtime version, is safer to test on a slice of real traffic. These changes affect behavior throughout the app in ways that are hard to wrap in a flag.

Infrastructure configuration changes. Changes to server tuning, connection pool sizes, caching behavior — these need to run on real infrastructure to measure their effect. A flag in application code can’t surface OS-level or infrastructure-level impacts.

For everything else — new UI, changed algorithms, new API endpoints, updated business logic — a feature flag rollout is faster to set up, easier to operate, and gives you better targeting control than an infrastructure canary.

Rollback

The practical advantage of a feature flag over a deployment rollback is speed and granularity. Rolling back a deployment takes minutes and reverts everything in that release. Flipping a flag takes seconds and affects only that feature.

When something goes wrong at 10% rollout, you open the dashboard and move the slider to 0%. The broken code path stops executing immediately for all users. Then you fix the bug and run the rollout again — without touching anything else that shipped in the same deployment.

If you want to skip the infrastructure overhead and roll out features gradually with percentage-based targeting, check out Flaggy.