DEV Community

Cover image for Standardizing Feature Flags Is Easy to Agree On. Migrating Safely Is the Hard Part.
Krishan Sharma
Krishan Sharma

Posted on

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

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
);
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

becoming:

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

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)
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

can safely become:

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

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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";
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 .
Enter fullscreen mode Exit fullscreen mode

Then explore a reviewable migration preview:

npx flaglint migrate --dry-run
Enter fullscreen mode Exit fullscreen mode

Resources:

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

Top comments (0)