React SDK - OpenFeature

The @westyx-nexus/openfeature-provider-react package bridges the Nexus React SDK into the OpenFeature Web SDK. It wraps an already-initialised NexusClient - the provider does not manage the client lifecycle, opens no second connection, and keeps no second cache.

Installation

npm install @westyx-nexus/sdk-react @westyx-nexus/openfeature-provider-react @openfeature/react-sdk

Also configure the npm registry for the Westyx Nexus scope - see Installation.

Quick start

Registering the provider from inside the tree wraps the client <NexusProvider> already created, rather than opening a second one:

import { useEffect, useState, type ReactNode } from 'react';
import { OpenFeature, useBooleanFlagValue } from '@openfeature/react-sdk';
import { NexusProvider, useNexus } from '@westyx-nexus/sdk-react';
import { createOpenFeatureProvider } from '@westyx-nexus/openfeature-provider-react';

function OpenFeatureBridge({ children }: { children: ReactNode }) {
  const client = useNexus();
  const [ready, setReady] = useState(false);

  useEffect(() => {
    let live = true;
    void OpenFeature.setProviderAndWait(createOpenFeatureProvider(client)).then(() => {
      if (live) setReady(true);
    });
    return () => {
      live = false;
    };
  }, [client]);

  return ready ? children : null;
}

export function App() {
  return (
    <NexusProvider config={{ baseUrl: 'https://blue-ocean-a5rx7.westyx.dev', apiKey: 'wxp_...' }}>
      <OpenFeatureBridge>
        <Checkout />
      </OpenFeatureBridge>
    </NexusProvider>
  );
}

function Checkout() {
  const showBanner = useBooleanFlagValue('banner.enabled', false);
  return showBanner ? <Banner /> : <CheckoutForm />;
}

If you create the client yourself rather than through <NexusProvider>, pass that instance straight to createOpenFeatureProvider.

Per-user targeting

When the evaluation context carries a targetingKey, a boolean evaluation is resolved for that user through the Nexus AB Testing add-on: the flag’s rollout percentage and cohort rules are applied to that identity, and the resolution reports TARGETING_MATCH.

await OpenFeature.setContext({ targetingKey: user.id, plan: 'pro', region: 'eu' });

// resolved for user.id, synchronously
const enabled = OpenFeature.getClient().getBooleanValue('checkout.v2', false);

Where the request happens

resolveBooleanEvaluation is synchronous in the OpenFeature Web SDK - there is no promise for it to await - and the Web SDK’s paradigm is a static evaluation context. So the provider asks the service when the context changes, not when a flag is read:

Trigger	What the provider does
`OpenFeature.setContext(...)`	Fetches the targeted values, and the Web SDK awaits it before the next evaluation.
`setProviderAndWait` with a context already carrying a targeting key	Fetches during `initialize`, so the first render is already targeted.
The client reports a configuration change (stream push or TTL poll)	Re-asks for the same identity, so a flag edited in the console reaches a targeted evaluation too.
A context change that alters neither the targeting key nor any string attribute	Nothing. A context object rebuilt with the same contents is a re-render, not a new question.
An evaluation	Nothing. It reads what the fetch produced.

One round trip covers every flag in the snapshot, so a page reading twenty flags costs one request, and concurrent triggers for the same identity coalesce into one. A snapshot with more than 200 flags is split into successive calls, which is the endpoint’s documented cap.

Attributes are strings

The service’s cohort matcher compares strings with eq / neq / in, so only string context fields are sent. A non-string field is left out and reported at debug level rather than converted - a coerced value that matches no rule is harder to diagnose than an absent one. Format at the call site (String(age), not age) and you know exactly what the rule is matched against. targetingKey is sent as the identity, never also as an attribute.

Reasons you will see

Reason	When
`STATIC`	No targeting key in the context - the synced snapshot is the answer. Also when the AB Testing add-on is not active for the project, where the snapshot is authoritative.
`TARGETING_MATCH`	A targeted answer for this identity. Percentage rollouts and cohort matches both report this: the endpoint returns a boolean per key and nothing that would distinguish them, so `SPLIT` cannot be reported honestly.
`STALE`	A targeting key is in force but there is no targeted answer for this flag - the request failed, or the flag entered the snapshot after the last fetch. The value is real, just not freshly targeted, and no error is reported: per the specification an error resolution returns the default value, which would hide a flag that is genuinely on behind one failed request.
`DEFAULT` + `FLAG_NOT_FOUND`	The service does not define this flag. No request is made - the endpoint answers `false` for a key it does not know, which is indistinguishable from “exists and off”.

If the add-on is not active

Projects without the AB Testing add-on get a 403 from the endpoint. The provider serves the snapshot with a STATIC reason and stops asking for five minutes at a time (addonSuppressionMs), so an inactive add-on costs one request per window rather than one per context change. It is a throttle, not a latch: buying the add-on starts producing targeted results within the window, with nothing to restart, and any success clears it immediately.

Provider options

createOpenFeatureProvider(client, {
  logger: console,
  addonSuppressionMs: 300_000,
});

Option	Default	Notes
`logger`	OpenFeature’s `DefaultLogger`	Where the provider’s diagnostics go: a dropped non-string context field, a failed targeted fetch, an inactive add-on. The fetch happens in `onContextChange` and `initialize`, and the Web SDK hands a logger only to the resolve methods - so the calls with something to report have none in scope, which is why this option exists. The default discards `debug`; pass `console` to see them.
`addonSuppressionMs`	`300000`	How long to stop calling the endpoint after the service reports the add-on inactive. Validated at construction; a negative or non-finite value is rejected naming the option and the value.

There is deliberately no cache-lifetime option, unlike the server-side bridges. The targeted values are replaced on a context change and on a configuration change - both events rather than deadlines - so a time-to-live would have nothing to govern.

Flag resolution

OpenFeature method	Nexus lookup	Result
`resolveBooleanEvaluation`	`client.hasFlag(key)`, then the targeted values or `client.getFlag(key)`	See Reasons you will see. `variant` is `"true"` or `"false"`.
`resolveStringEvaluation`	`client.getConfig(key)`	`STATIC` if present and a string; `DEFAULT` + `FLAG_NOT_FOUND` if absent or JSON `null`; `ERROR` + `TYPE_MISMATCH` otherwise.
`resolveNumberEvaluation`	`client.getConfig(key)`	`STATIC` if present and a number, or a `bigint` a `number` holds exactly; `DEFAULT` + `FLAG_NOT_FOUND` if absent or JSON `null`; `ERROR` + `TYPE_MISMATCH` otherwise - including for a numeric string, which is not a number.
`resolveObjectEvaluation`	`client.getConfig(key)`	`STATIC` if present and an object or array; `DEFAULT` + `FLAG_NOT_FOUND` if absent or JSON `null`; `ERROR` + `TYPE_MISMATCH` for a primitive. No `variant`: a composite value has no short semantic identifier.

Boolean flags come from feature flags; string, number and object evaluations come from config values. Config values are never targeted - evaluate-ab is a flag concept, so there is no such thing as a targeted config value. Inside a resolved object or array, an integer beyond Number.MAX_SAFE_INTEGER is carried as its exact decimal string, at any depth - OpenFeature’s JsonValue has no numeric slot that holds it exactly, and the decimal string is the lossless one, so the resolved value survives JSON.stringify. Ordinary numbers are untouched; parse the string with BigInt(value) where the magnitude matters. A TYPE_MISMATCH message names the type that arrived, so it is actionable without opening the configuration.

Live updates

The provider subscribes to the NexusClient via client.subscribe() in initialize(). When the Nexus cache refreshes (stream push or TTL poll) it emits ProviderEvents.ConfigurationChanged, and OpenFeature re-evaluates the flags in components using the standard hooks. The client’s listener also fires for a stream state transition, for a 304 and for the billing and quarantine flags, none of which changed a flag; the provider compares client.snapshotRevision and acts only on a real configuration change, so a reconnect costs no request and triggers no re-render.

Nexus backend ──stream──▶ NexusClient.sync() ──notify──▶ NexusReactProvider
                                                                │
                                                     emit(ConfigurationChanged)
                                                                │
                                                 OpenFeature re-evaluates flags

The same listener re-asks for the targeted values. That refresh emits a second ConfigurationChanged only when the values actually moved: announcing an unchanged refresh would re-render every component bound to a flag on every sync.

Cleanup

On provider shutdown (OpenFeature.clearProviders() or replacing the provider), onClose() unsubscribes the listener and drops the stored identity.

API

`NexusReactProvider`

class NexusReactProvider implements Provider {
  constructor(client: NexusClient, options?: NexusProviderOptions);
  readonly runsOn: 'client';
  readonly metadata: { name: 'Nexus React Provider' };
  readonly events: OpenFeatureEventEmitter;
  initialize(context?: EvaluationContext): Promise<void>;
  onContextChange(oldContext: EvaluationContext, newContext: EvaluationContext): Promise<void>;
  onClose(): Promise<void>;
  resolveBooleanEvaluation(key, default, ctx?, logger?): ResolutionDetails<boolean>;
  resolveStringEvaluation(key, default, ctx?, logger?): ResolutionDetails<string>;
  resolveNumberEvaluation(key, default, ctx?, logger?): ResolutionDetails<number>;
  resolveObjectEvaluation<T>(key, default, ctx?, logger?): ResolutionDetails<T>;
}

`createOpenFeatureProvider`

function createOpenFeatureProvider(
  client: NexusClient,
  options?: NexusProviderOptions,
): NexusReactProvider;

Convenience factory; equivalent to new NexusReactProvider(client, options).

Package registry

The @westyx-nexus/openfeature-provider-react sub-package is published separately from @westyx-nexus/sdk-react. Add the same GitLab npm registry configuration - see Installation.

Version

Latest release: v0.16.0. The bridge requires @westyx-nexus/sdk-react v0.16.0 or newer - it is declared as a peer dependency, so npm will tell you if the two are out of step. The floor follows the release, so a consumer never resolves an SDK older than the bridge that wraps it. @openfeature/core is a direct dependency of the bridge. @openfeature/web-sdk declares it as a peer and imports it at runtime, so it must be present; it is resolved for you.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

React SDK - OpenFeature

Installation

Quick start

Per-user targeting

Where the request happens

Attributes are strings

Reasons you will see

If the add-on is not active

Provider options

Flag resolution

Live updates

Cleanup

API

`NexusReactProvider`

`createOpenFeatureProvider`

Package registry

Version

​Installation

​Quick start

​Per-user targeting

​Where the request happens

​Attributes are strings

​Reasons you will see

​If the add-on is not active

​Provider options

​Flag resolution

​Live updates

​Cleanup

​API

​NexusReactProvider

​createOpenFeatureProvider

​Package registry

​Version

Installation

Quick start

Per-user targeting

Where the request happens

Attributes are strings

Reasons you will see

If the add-on is not active

Provider options

Flag resolution

Live updates

Cleanup

API

`NexusReactProvider`

`createOpenFeatureProvider`

Package registry

Version