Node.js OpenFeature provider

The Unleash OpenFeature Node.js provider lets server-side Node.js applications evaluate Unleash feature flags through the OpenFeature API.

The provider wraps the Unleash Node.js SDK and uses the same backend SDK behavior for polling, local evaluation, caching, metrics, and shutdown. The provider creates and starts the Unleash client when it initializes and destroys it, with a final metrics flush, when OpenFeature shuts down.

Requirements

• Node.js 22.13 or later

Installation

Install the provider together with its peer dependencies, the OpenFeature server SDK and the Unleash Node.js SDK:

$
npm install @unleash/openfeature-node-provider @openfeature/server-sdk unleash-client

Configuration

Create an UnleashProvider with the same options you would pass to the Unleash Node.js SDK client, then register it with OpenFeature.

1
import { OpenFeature } from '@openfeature/server-sdk';
2
import { UnleashProvider } from '@unleash/openfeature-node-provider';
3
4
const provider = new UnleashProvider({
5
  appName: 'my-node-app',
6
  url: '<YOUR_UNLEASH_URL>/api',
7
  customHeaders: {
8
    Authorization: '<YOUR_API_TOKEN>'
9
  }
10
});
11
12
await OpenFeature.setProviderAndWait(provider);

setProviderAndWait starts the Unleash SDK and waits for startup to complete before the provider is registered for use. After startup, the SDK continues refreshing feature flag data in the background.

If you need direct access to the underlying Unleash client, use provider.unleashClient.

Evaluate a flag

Build an OpenFeature client and evaluate flags through the OpenFeature API:

1
const client = OpenFeature.getClient();
2
3
const enabled = await client.getBooleanValue('my-feature', false, {
4
  targetingKey: 'user-123'
5
});

The provider supports all OpenFeature evaluation methods. Boolean evaluation uses the flag’s enabled state. All other types resolve from the payload of the flag’s variant:

• String values accept string and csv payloads.
• Number values accept number payloads.
• Object values accept json payloads.

If the flag doesn’t exist, the flag is disabled, or the variant payload is missing or has a different type, the evaluation returns the default value. The detail methods, such as getBooleanDetails, additionally report the evaluation reason, the assigned variant name, and flag metadata with featureEnabled and payloadType fields.

Context mapping

The provider maps the OpenFeature evaluation context to an Unleash context before each evaluation. You can set a global context with OpenFeature.setContext() and override it per evaluation by passing a context to the evaluation method.

The following OpenFeature fields map directly to top-level Unleash context fields:

• currentTime
• userId
• sessionId
• remoteAddress
• environment
• appName

If you set targetingKey, the provider maps it to userId. The targetingKey takes precedence over a userId field set on the evaluation context.

The provider adds all other fields to the Unleash context properties. It discards nested values, such as arrays and objects.

Events

The provider translates Unleash client events into OpenFeature provider events:

1
import { ProviderEvents } from '@openfeature/server-sdk';
2
3
provider.events.addHandler(ProviderEvents.ConfigurationChanged, () => {
4
  console.log('Flag configuration changed');
5
});

Shutdown

Shut down OpenFeature when your application exits. This also shuts down the underlying Unleash client and flushes any pending metrics.

1
await OpenFeature.close();

Example

To try the provider against your Unleash instance, clone the provider repository and run the sample application with your Unleash URL and API token:

$
cd sample
$
npm install
$
UNLEASH_URL='<YOUR_UNLEASH_URL>/api' \
>
UNLEASH_API_TOKEN='<YOUR_API_TOKEN>' \
>
npm start