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
| Concept | What it is |
|---|---|
| API | The global entry point. You register providers, global context and hooks on it. |
| Provider | The adapter to a flag system. It resolves a flag key and context to a value. |
| Client | What your code calls: getBooleanValue, getStringValue, getNumberValue, getObjectValue. |
| Evaluation context | Who is asking: a targetingKey (usually the user or account id) plus attributes such as plan or country. |
| Hooks | Code that runs before, after, on error and finally around every evaluation: logging, metrics, tracing, validation. |
| Events | Notifications from the provider: ready, configuration changed, stale, error. |
| Domains | Named 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:
- Copy the flags and rules to the new system, keeping the same flag keys.
- Check that both give the same answers for real contexts, especially percentage rollouts: if the new system hashes users differently, people switch variation.
- 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
ERRORand an error code such asFLAG_NOT_FOUNDorPROVIDER_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