Documentation
Flagdeck ships a server-side OpenFeature provider so teams already standardized on OpenFeature can adopt Flagdeck by swapping a provider instead of rewriting evaluation calls. The provider wraps the JavaScript SDK and translates between OpenFeature's context and result shapes and Flagdeck's native ones. The native evaluation model and the SDK contract do not change.
bash
# Using npm
npm install @flagdeck/openfeature @flagdeck/js @openfeature/server-sdk
# Using yarn
yarn add @flagdeck/openfeature @flagdeck/js @openfeature/server-sdk
# Using pnpm
pnpm add @flagdeck/openfeature @flagdeck/js @openfeature/server-sdk
@openfeature/server-sdk is a peer dependency. @flagdeck/js is the client the provider wraps.
Set the Flagdeck provider once at startup, then evaluate flags through the OpenFeature client.
ts
import { OpenFeature } from '@openfeature/server-sdk';
import { FlagdeckProvider } from '@flagdeck/openfeature';
// The SDK key is scoped to one project and environment. Read it from the environment.
await OpenFeature.setProviderAndWait(
new FlagdeckProvider({ apiKey: process.env.FLAGDECK_SDK_KEY })
);
const client = OpenFeature.getClient();
const showNewUi = await client.getBooleanValue('new-ui', false, {
targetingKey: user.id, // becomes Flagdeck's userId
email: user.email, // becomes attributes.email
});
You can also hand the provider an already configured @flagdeck/js client instead of options:
ts
import { Flagdeck } from '@flagdeck/js';
import { FlagdeckProvider } from '@flagdeck/openfeature';
new FlagdeckProvider(new Flagdeck({ apiKey: process.env.FLAGDECK_SDK_KEY }));
OpenFeature's evaluation context is a single targetingKey plus an open map of attributes. Flagdeck's context has two top-level identities, userId and sessionId, and resolves everything else as a dot path into attributes. The provider maps between them:
| OpenFeature context | Flagdeck context | Notes |
|---|---|---|
targetingKey | userId | OpenFeature's bucketing identity is Flagdeck's primary identity, so rollout and variant stickiness line up one to one. |
sessionId (string) | sessionId | Promoted to the native slot so anonymous stickiness (userId or sessionId) keeps working. |
any other key: value | attributes[key] | Scalars and nested objects pass through unchanged. The engine resolves dot paths such as account.id. |
Because targetingKey becomes userId, bucketing lines up with the rest of your Flagdeck usage. A targeting rule on account.id or user.metadata.tier resolves the same way it does through the native SDK.
OpenFeature has typed accessors for boolean, string, number, and object values. Each one checks the returned value's runtime type. If a flag resolves to a value of a different type, the provider returns your default value with a TYPE_MISMATCH error rather than coercing it.
ts
const maxItems = await client.getNumberValue('max-items', 20, {
targetingKey: user.id,
});
const uiConfig = await client.getObjectValue(
'ui-config',
{ theme: 'light' },
{ targetingKey: user.id }
);
Flagdeck's evaluation source maps to an OpenFeature resolution reason:
| Flagdeck source | OpenFeature reason |
|---|---|
user_targeting, environment_targeting, global_targeting | TARGETING_MATCH |
environment_rollout, global_rollout, variant, variant_fallback | SPLIT |
default | DEFAULT |
offline | CACHED |
| error (flag missing, invalid context) | ERROR |
The provider never throws to your application. If a flag is missing, the context is invalid, or the network fails, it returns the default value you passed, along with an error code (FLAG_NOT_FOUND, INVALID_CONTEXT, or GENERAL) and the reason ERROR.
This is a server provider, built on @openfeature/server-sdk, where context is passed with each evaluation. A browser provider built on @openfeature/web-sdk is planned, and it reuses the same context mapping.