DEV Community: Krishan Sharma

Your Node.js Codebase Has Flag Debt. Here's How to Find It in 30 Seconds.

Krishan Sharma — Tue, 02 Jun 2026 15:54:10 +0000

Most teams don't know how many feature flags are in their codebase.

They know they have some. They think they cleaned up most. They're not sure about the rest.

One command changes that:

npx flaglint audit ./src

No API key. No credentials. No dashboard to sign up for. Just your source code and an honest answer.

The Problem Nobody Talks About

According to LaunchDarkly's best practices, most release flags should live for only days to weeks — yet many remain in codebases for months or years.

That's not a LaunchDarkly problem. It's a universal one.

Flags accumulate because adding one is fast and removing one is work. You ship the feature, move on, and the flag stays. Six months later a new engineer asks "is this safe to delete?" and nobody knows. So it stays another six months.

Stale flags make code "more complex and harder to maintain," as developers spend extra time navigating obsolete conditionals. Unused toggles may degrade performance or even inadvertently expose features or data.

And here's the part that stings: developers spend 33–42% of their time dealing with technical debt and maintenance. Feature flag debt is a quiet contributor to that number.

What "Flag Debt" Actually Looks Like

Here's a real checkout service. Nothing exotic — a Node.js backend with LaunchDarkly calls spread across five files.

// checkout.ts
export async function isCheckoutV2Enabled(user: User): Promise<boolean> {
  const ctx = { targetingKey: user.id, email: user.email, plan: user.plan };
  return ldClient.boolVariation("checkout-v2", ctx, false);
}

// discounts.ts
const flagKey = `discount-${experimentName}`;
const enabled = await ldClient.boolVariation(flagKey, ctx, false);

// analytics.ts
const state = await ldClient.allFlagsState(ctx);

Three different patterns. Three very different levels of risk.

The first one is fine — static key, known type, safely removable.

The second one is a problem — the key is a template literal. You can't statically know which flag it evaluates at runtime.

The third one is a migration blocker — allFlagsState has no OpenFeature equivalent. It requires an architecture decision before you touch it.

Most teams treat all three the same. They shouldn't.

The Audit Command

FlagLint v0.6.0 ships with a new command: flaglint audit.

It scans your codebase, classifies every flag call by risk level, and tells you exactly what you're dealing with — before you touch anything.

npx flaglint@latest audit ./src

Running it against the enterprise checkout service above produces:

✓ Audit complete: 13 flags — 3 high risk, 10 medium risk, 0 low risk

With the full table:

Flag Key	Risk	Usages	Reasons
`dynamic`	🔴 High	7	dynamic key
`checkout-experiment`	🔴 High	1	detail evaluation
`*`	🔴 High	1	bulk call
`checkout-v2`	🟡 Medium	1	safely automatable
`payment-provider`	🟡 Medium	1	safely automatable
`discount-config`	🟡 Medium	1	safely automatable, json variation
...

High risk means the call needs manual review before anything happens:

Dynamic key — the flag key is a variable or template literal. FlagLint can't tell which flag you're evaluating.
Detail evaluation — boolVariationDetail returns metadata with no direct OpenFeature equivalent.
Bulk call — allFlagsState is an architecture decision, not a line-by-line migration.

Medium risk means FlagLint can automate the migration safely, but the flag is still a direct vendor call that will need to move eventually.

Low risk means the flag is already migrated or has no debt signals.

Three Output Formats

# Markdown — good for PRs and docs
npx flaglint audit ./src --format markdown

# JSON — good for CI pipelines and dashboards
npx flaglint audit ./src --format json --output audit.json

# HTML — shareable report for engineering reviews
npx flaglint audit ./src --format html --output flag-debt.html

The HTML report is the one worth sharing with your team or your manager. It's a single self-contained file — no server needed, just open it in a browser. Drop it in a PR, a Jira ticket, or an email. It shows exactly which flags need attention and why.

From Audit to Action

The audit is informational. It doesn't touch your code.

Once you've seen your report, FlagLint has two more commands for when you're ready to act:

Preview the migration:

npx flaglint migrate ./src --dry-run

This shows before/after diffs for every safely automatable call — the Medium risk flags from your audit. Nothing is written to disk.

--- checkout.ts
+++ checkout.ts
-  return ldClient.boolVariation("checkout-v2", ctx, false);
+  return openFeatureClient.getBooleanValue("checkout-v2", false, ctx);

Note the argument order. LaunchDarkly is (flagKey, context, fallback). OpenFeature is (flagKey, fallback, context). A manual find-and-replace migration silently swaps them — that's a production bug waiting to happen. FlagLint gets it right because it uses AST analysis, not text matching.

Apply the migration:

npx flaglint migrate ./src --apply

Rewrites only the calls that are proven safe. Dynamic keys, detail methods, and bulk calls are skipped and reported for manual review. Won't run on a dirty git tree. Idempotent — safe to run twice.

Lock the boundary in CI:

npx flaglint validate ./src --no-direct-launchdarkly

Exits 1 if any direct LaunchDarkly evaluation call appears in your codebase. Add this to your GitHub Actions workflow and the migration can't silently reverse.

Why No API Key?

Every major feature flag platform has a tool that connects to their API to show you flag health. Those tools are useful, but they only see flags that exist in their own system. They won't show you a LaunchDarkly flag if you're asking a Statsig dashboard.

More importantly — they're built to keep you in their platform. No vendor builds the exit ramp for their own tool.

FlagLint only looks at your source code. It doesn't know what's in your LaunchDarkly dashboard. It doesn't need to. The question it answers is: what is your code actually doing right now?

That's a different question, and it has a different answer.

The Full Workflow

# Step 1: Understand what you have
npx flaglint audit ./src --format html --output flag-debt.html

# Step 2: Preview safe migrations
npx flaglint migrate ./src --dry-run

# Step 3: Apply the safe ones
npx flaglint migrate ./src --apply

# Step 4: Lock it in CI
npx flaglint validate ./src --no-direct-launchdarkly

Four commands. Covers the full lifecycle from "what do we have?" to "this can never regress."

Try It

npx flaglint@latest audit ./src

No install required. Works on any Node.js 20+ project using the LaunchDarkly Node.js server SDK (both launchdarkly-node-server-sdk and @launchdarkly/node-server-sdk).

→ GitHub — MIT licensed, open source

→ npm

→ Docs

FlagLint is a vendor-neutral CLI for LaunchDarkly → OpenFeature migrations. v0.6.0 adds flag debt auditing. Read the changelog →

Tags: node devops javascript typescript openfeature launchdarkly featureflags technicaldebt opensource featureflags

Standardizing Feature Flags Is Easy to Agree On. Migrating Safely Is the Hard Part.

Krishan Sharma — Thu, 28 May 2026 12:02:08 +0000

Why I built FlagLint, an open-source CLI for moving direct LaunchDarkly Node.js usage behind an OpenFeature boundary

Feature flags usually begin as a simple engineering decision.

A team needs to release gradually. A developer adds a flag. The application evaluates it through the provider SDK. The rollout succeeds.

Then the pattern repeats.

One feature becomes ten. One service becomes dozens. Over time, application code starts to accumulate direct calls to a provider-specific API:

const enabled = await ldClient.boolVariation(
  "checkout-v2",
  context,
  false
);

There is nothing wrong with that call by itself. LaunchDarkly is doing exactly what it is supposed to do: providing feature-flag management and evaluation.

The problem appears later, when a platform team wants a consistent application-facing abstraction across services.

Maybe the organization wants to standardize on OpenFeature, the CNCF-incubating, vendor-agnostic feature-flag API. Maybe teams want feature-flag instrumentation, governance, or shared patterns implemented once at a platform boundary instead of separately inside each service.

At that point, the difficult question is no longer:

Should we standardize feature-flag evaluation?

The difficult questions are:

Where are all the direct SDK calls? Which ones can be migrated safely? Which ones require human review? And how do we stop new direct calls from returning after migration?

That is the problem I built FlagLint to solve.

OpenFeature Does Not Mean Replacing LaunchDarkly

A common misconception in migration conversations is that introducing OpenFeature means replacing the current feature-flag provider.

It does not.

OpenFeature standardizes the evaluation API that application code uses. A provider still performs the actual evaluation. LaunchDarkly offers an official OpenFeature provider for its Node.js server-side SDK, so a Node.js service can continue using LaunchDarkly as its feature-flag provider while application code evaluates flags through OpenFeature.

Conceptually, the change looks like this:

// Direct provider-specific application usage
await ldClient.boolVariation("checkout-v2", context, false);

becoming:

// Standard application-facing evaluation API
await openFeatureClient.getBooleanValue("checkout-v2", false, context);

LaunchDarkly remains behind the provider boundary. The application code moves toward a standard interface.

That distinction matters. Platform standardization should not require an unnecessary provider replacement project.

Why This Migration Is More Dangerous Than It Looks

At first glance, this appears to be a simple codemod problem: find a method call and rename it.

But feature-flag migrations carry runtime behavior. An incorrect transformation can change what users see in production.

For example, the LaunchDarkly and OpenFeature method signatures differ in argument order:

// LaunchDarkly
ldClient.boolVariation(key, context, fallback)

// OpenFeature
openFeatureClient.getBooleanValue(key, fallback, context)

A careless rewrite can silently swap the fallback value and context.

There are additional complications:

a flag key may be a dynamic expression rather than a static string;
a call may request evaluation details rather than only a flag value;
code may use bulk flag-state APIs;
a fallback type may not be statically clear;
a service may import a shared platform-owned OpenFeature client using a local alias;
the provider bootstrap file may legitimately reference LaunchDarkly directly;
asynchronous behavior must be preserved exactly.

In a migration involving feature flags, “we rewrote most of it automatically” is not enough. The important question is whether the automation knows when not to rewrite code.

The Design Principle Behind FlagLint: Conservative Automation

FlagLint is an open-source CLI focused on a specific workflow:

Help Node.js teams inventory direct LaunchDarkly server SDK evaluations, migrate only provably safe call sites to OpenFeature, and enforce the new boundary in CI.

Its scope is deliberately narrow today. FlagLint supports JavaScript and TypeScript code using the LaunchDarkly Node.js server-side SDK package forms:

@launchdarkly/node-server-sdk
launchdarkly-node-server-sdk

It is not trying to claim every language, every SDK, or every feature-flag lifecycle problem.

FlagLint uses AST-based analysis to identify direct LaunchDarkly Node.js evaluation calls. It can automatically transform typed static evaluations only when the important parts are explicit:

the flag key;
the fallback value and type;
the evaluation context;
a proven OpenFeature client binding.

For example:

// Before
return await ldClient.boolVariation("checkout-v2", ctx, false);

can safely become:

// After
return await openFeatureClient.getBooleanValue("checkout-v2", false, ctx);

But FlagLint does not automatically rewrite uncertain patterns. Dynamic keys, detail evaluation methods, bulk calls, unknown fallbacks, browser or React SDK usage, and ambiguous bindings remain visible for human review.

This is not a limitation to hide. It is the safety model.

A migration tool should automate the obvious cases and make uncertainty impossible to ignore.

The Workflow: Scan, Migrate, Enforce

FlagLint is designed around three steps.

1. Inventory direct SDK coupling

Before a migration starts, teams need to understand what exists in the codebase:

npx flaglint scan ./src

The scan identifies direct LaunchDarkly Node.js server SDK evaluation calls, their files, flag keys, call types, and patterns that need manual review. Reports can be emitted in formats including Markdown, JSON, HTML, and SARIF.

This is useful for both developers and platform teams. Before changing code, you can see whether a service is mostly straightforward or full of patterns that require careful migration planning.

2. Preview and apply safe transformations

Next, teams can generate a migration plan and inspect diffs before touching source code:

npx flaglint migrate ./src --dry-run

FlagLint generates reviewable before/after diffs. When a file already contains a proven OpenFeature client binding, including an approved imported shared client binding, the preview uses that exact binding.

For example, a service may already import a platform-owned client with an alias:

import { openFeatureClient as flags } from "../platform/feature-flags.js";

FlagLint preserves that architecture and previews the migration using flags.getBooleanValue(...) rather than inventing a new local client.

When ready, safe transformations can be applied:

npx flaglint migrate ./src --apply

The apply mode is guarded. It requires a proven OpenFeature client binding, refuses to write into a dirty Git working tree unless explicitly overridden, does not insert provider bootstrap setup automatically, and does not rewrite uncertain patterns.

3. Prevent the migration from reversing

Migration is not complete if new direct provider SDK calls can quietly appear in future pull requests.

Once a service has completed the boundary migration, FlagLint can enforce it in CI:

npx flaglint validate ./src --no-direct-launchdarkly

Validation can emit SARIF findings so direct LaunchDarkly policy violations can appear as annotations in code scanning and pull-request review flows.

This turns a one-time refactor into an enforceable engineering standard.

An Important Boundary: FlagLint Is Not a Stale-Flag Platform

There is a broader category of feature-flag debt: flags that are fully rolled out, inactive, unused at runtime, or ready for deletion in the provider platform.

That is an important problem, but it requires lifecycle and runtime information that source code alone cannot prove.

FlagLint does not currently claim to delete stale flags, inspect production evaluations, replace LaunchDarkly lifecycle tooling, or reduce feature-flag billing.

Its current problem is more precise:

Where is application code directly coupled to the LaunchDarkly Node.js SDK, what can move safely behind OpenFeature, and can we enforce that boundary afterward?

That focus is intentional. Tools earn trust by being accurate about what they know and what they do not know.

What I Learned Building the First Release

The technical work was only one part of the project. The harder part was defining safe behavior.

A migration CLI for application infrastructure cannot be aggressive by default. It needs to be explainable. Every automated rewrite should be reviewable. Every skipped pattern should make sense to the engineer reading the report.

During post-release validation of FlagLint v0.5.0, I found a good example of why that matters. A dry-run using a proven aliased OpenFeature client binding correctly previewed a safe transformation, but the CLI still printed global guidance implying provider setup was required. The transformation itself was correct, but the message was contradictory.

That mattered because trust in migration tools is not only about whether they edit code correctly. It is also about whether their explanations match their behavior.

In v0.5.1, I fixed that messaging so proven bindings are described accurately, missing bindings still receive setup guidance, and mixed cases clearly scope guidance only to diffs that need it.

No safety boundary was weakened to make the tool appear more capable.

That is the standard I want FlagLint to maintain as it grows.

What Comes Next

The next challenge is not just transforming code. It is helping real teams adopt the boundary incrementally.

In a small service, a team may be able to migrate all direct SDK calls and enable strict CI enforcement immediately.

In an established codebase, that may not be realistic. A platform team may find hundreds of existing direct evaluations spread across services. They still need a way to prevent new vendor-coupled access while reducing existing usage over time.

That leads to the next direction for FlagLint: team adoption and governance workflows, including the ability to measure migration readiness across services and support gradual CI rollout without requiring a big-bang refactor.

The goal remains simple:

Make the safer architecture easier to adopt than the shortcut.

Try FlagLint

FlagLint is open source and available today as v0.5.1.

Run it against a Node.js service using the LaunchDarkly server-side SDK:

npx flaglint scan .

Then explore a reviewable migration preview:

npx flaglint migrate --dry-run

Resources:

Website: flaglint.dev
GitHub: github.com/flaglint/flaglint
npm: npmjs.com/package/flaglint
OpenFeature: openfeature.dev
LaunchDarkly OpenFeature Node.js provider documentation: LaunchDarkly docs

I would especially value feedback from Node.js backend engineers and platform teams already using LaunchDarkly:

What direct SDK patterns exist in your repositories?
Do you use internal wrappers or shared feature-flag clients?
What would make an OpenFeature migration safe enough to evaluate in a real service?

The best developer tools are shaped by the real codebases they have to survive.

devops #typescript #javascript #opensource #featureflags