Skip to main content
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

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. The OpenFeature hooks read their client from <OpenFeatureProvider>, so the bridge renders it around its children:
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.

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: 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 calls of at most 200 keys - the endpoint’s documented cap - sent concurrently; one failed call fails the whole refresh.

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 warn 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

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.

If the environment is switched off

While the environment is switched off (403 environment_disabled) or the service is in emergency lockdown (423 service_locked), the endpoint refuses evaluateAB. The provider keeps the targeted values it already had (STALE for anything it has no answer for) and sends no request - for any context - for the same addonSuppressionMs window, with one warning: retrying cannot succeed until the environment is switched back on. Any success clears it.

Provider options

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

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.
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

createOpenFeatureProvider

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

Versions

The bridge and the SDK are released together under one version number. The bridge declares the SDK as a peer dependency with its own version as the floor, so npm reports a mismatch and a consumer never resolves an SDK older than the bridge that wraps it. @openfeature/core and @openfeature/web-sdk are dependencies of the bridge, resolved for you; npm installs one copy of each next to @openfeature/react-sdk.