Guide

OpenFeature: a practical guide with code

What OpenFeature is, how its pieces fit together, how it behaves on the server and in the browser, and how it lets you change feature flag vendors without rewriting the code that checks flags.

OpenFeature is an open, vendor-neutral API for feature flags. Your code calls one standard interface to evaluate flags, and a provider connects that interface to whichever flag system you use. Changing vendors means changing the provider, not every flag check.

Why OpenFeature exists

Every feature flag vendor used to ship its own SDK with its own method names, context format and error behaviour. Flag checks spread through a codebase, so switching vendors meant touching hundreds of call sites, and libraries could not check flags without picking a vendor for their users.

OpenFeature fixes the interface instead of the implementation. It is a specification plus SDKs for many languages, including JavaScript and TypeScript (server, web and React), Java, Go, .NET, Python, PHP and Ruby. It is a Cloud Native Computing Foundation project at the incubating level, and most feature flag platforms publish a provider for it.

Core concepts

ConceptWhat it is
APIThe global entry point. You register providers, global context and hooks on it.
ProviderThe adapter to a flag system. It resolves a flag key and context to a value.
ClientWhat your code calls: getBooleanValue, getStringValue, getNumberValue, getObjectValue.
Evaluation contextWho is asking: a targetingKey (usually the user or account id) plus attributes such as plan or country.
HooksCode that runs before, after, on error and finally around every evaluation: logging, metrics, tracing, validation.
EventsNotifications from the provider: ready, configuration changed, stale, error.
DomainsNamed providers, so one application can use more than one flag source.

Evaluating a flag

Register a provider once at startup, then ask a client for values. The second argument is the default value, returned whenever the flag cannot be evaluated:

import { OpenFeature } from '@openfeature/server-sdk';
import { RailflagProvider } from '@railflag/sdk-node';

await OpenFeature.setProviderAndWait(new RailflagProvider({
  sdkKey: process.env.RAILFLAG_SERVER_KEY,
  baseUrl: process.env.RAILFLAG_RELAY_URL,
}));
const client = OpenFeature.getClient();

const on = await client.getBooleanValue('new-checkout', false, { targetingKey: user.id, plan: user.plan });

When you need to know why a value was returned, use the details variant. It adds the variant name, a reason and, on failure, an error code:

const details = await client.getBooleanDetails('new-checkout', false, context);
// { flagKey: 'new-checkout', value: true, variant: 'on', reason: 'TARGETING_MATCH' }
// or, if the key is wrong: { value: false, reason: 'ERROR', errorCode: 'FLAG_NOT_FOUND' }

Evaluation never throws. A missing flag, a type mismatch or a provider that is not ready all return your default, which is why the default should always be the safe choice.

Evaluation context

Context is how targeting rules know who is asking. OpenFeature merges it from several levels, with the most specific winning: global (set on the API), client, and the context passed to a single call.

OpenFeature.setContext({ service: 'checkout-api', region: 'eu-west' }); // every evaluation

await client.getBooleanValue('new-checkout', false, {
  targetingKey: user.id,   // what percentage rollouts hash on
  plan: user.plan,
  country: user.country,
});

The targetingKey matters most. Percentage rollouts hash it to decide who is in, so it must be stable for a user (or an account, in B2B products) across requests and services.

Server SDKs vs client SDKs

OpenFeature has two flavours of SDK, because servers and browsers evaluate flags differently:

  • Server (dynamic context). One process serves many users, so context is passed on every call and evaluation is asynchronous. Good providers keep the rules in memory and evaluate locally.
  • Client (static context). A browser or mobile app has one user at a time. You set the context once with OpenFeature.setContext(), the provider fetches values for that user, and evaluation is synchronous, so it fits render code.
import { OpenFeature } from '@openfeature/web-sdk';
import { RailflagWebProvider } from '@railflag/sdk-js';

await OpenFeature.setProviderAndWait(new RailflagWebProvider({ clientKey: 'cli_…', baseUrl: RELAY_URL }), { targetingKey: user.id });
const on = OpenFeature.getClient().getBooleanValue('new-checkout', false); // synchronous

await OpenFeature.setContext({ targetingKey: otherUser.id }); // after sign-in: values are fetched again

Keep targeting rules on the server side of that split. A client provider should receive evaluated values, not the rules and segment lists that produced them, because anything in the browser is public.

Hooks: logging, metrics and tracing

Hooks run around every evaluation without touching call sites. A common first hook records what was served:

import { OpenFeature, type Hook } from '@openfeature/server-sdk';

const auditHook: Hook = {
  after(hookContext, details) {
    logger.debug({ flag: hookContext.flagKey, value: details.value, reason: details.reason });
  },
  error(hookContext, err) {
    logger.warn({ flag: hookContext.flagKey, err }, 'flag evaluation failed, default served');
  },
};

OpenFeature.addHooks(auditHook);

Hooks can be added globally, per client or per call. The OpenFeature project also publishes ready-made hooks, for example for OpenTelemetry traces and metrics.

Testing code that uses flags

Because your code depends on the OpenFeature API, not on a vendor, tests can swap in the in-memory provider that ships with the SDK:

import { InMemoryProvider, OpenFeature } from '@openfeature/server-sdk';

await OpenFeature.setProviderAndWait(new InMemoryProvider({
  'new-checkout': { variants: { on: true, off: false }, defaultVariant: 'on', disabled: false },
}));

Switching feature flag vendors

With every check going through OpenFeature, moving to another vendor has three steps, none of which touch call sites:

  1. Copy the flags and rules to the new system, keeping the same flag keys.
  2. Check that both give the same answers for real contexts, especially percentage rollouts: if the new system hashes users differently, people switch variation.
  3. Change the provider line at startup, one service and one environment at a time. Domains let both providers run side by side while you compare.

Step 2 is where migrations usually go wrong. Railflag's migration tooling reproduces AB Tasty's and Unleash's bucketing and compares decisions for sampled users before anything changes in Production.

Choosing a provider

The API is the same everywhere, so the provider decides how flags behave in production. Questions worth asking:

  • Where is the flag evaluated? In your process (fast, keeps working during outages) or by a remote call on every check?
  • How do changes arrive? Streaming in about a second, or polling every minute?
  • Is the answer the same in every language? A user should get the same variation from your API, your web app and your batch jobs.
  • What reaches the browser? Values only, or the full rule set?
  • Who can change Production? Is there review and an audit log?

Frequently asked questions

Is OpenFeature a feature flag service?
No. OpenFeature is a vendor-neutral API and a set of SDKs. It does not store flags or rules. A provider connects it to the system that does, such as a hosted feature flag platform, flagd, or your own configuration.
Does OpenFeature add latency to flag checks?
The API itself is a thin layer. Latency depends on the provider: a provider that evaluates rules in memory answers in microseconds, while one that calls a remote service on every check adds a network round trip.
What happens if a flag cannot be evaluated?
Evaluation never throws. The SDK returns the default value you passed in, and the details variant of the call reports the reason ERROR and an error code such as FLAG_NOT_FOUND or PROVIDER_NOT_READY.
Can I use two feature flag providers at once?
Yes. OpenFeature domains bind a provider to a name, and clients created with that name use it. This is useful during a migration or when one part of a system uses a different flag source.
Who maintains OpenFeature?
OpenFeature is an open source project of the Cloud Native Computing Foundation (CNCF), at the incubating maturity level, with contributors from many feature flag vendors and users.

An OpenFeature provider that evaluates in your process

Railflag's providers for Node, the browser, Python, Go and Java answer from memory, get changes within a second, and give the same answer in every language.

Start for free