OpenFeature Web Provider - Usage

Register the provider

Call setProviderAndWait once at application startup. It awaits the provider’s initialize, which performs the first /v1/sync call and opens the event stream before the promise resolves, so the first evaluation reads real values rather than defaults.

import { OpenFeature } from '@openfeature/web-sdk';
import { NexusProvider } from '@westyx-nexus/openfeature-web-provider';

await OpenFeature.setProviderAndWait(
  new NexusProvider({
    baseUrl: 'https://blue-ocean-a5rx7.westyx.dev', // the service endpoint
    apiKey: 'wxp_...',                              // a public (browser) key
  }),
);

setProviderAndWait rejects if the service cannot be read. A provider that cannot read the service is not ready, and reporting otherwise would serve every caller’s default as though it were an answer. Which error arrives says whether it is worth trying again. A failure only a change to what you passed in can fix - a rejected API key, a base URL naming no service, a configuration value the client will not accept - arrives as OpenFeature’s own ProviderFatalError, carrying error code PROVIDER_FATAL. The client goes to FATAL, and the SDK stops calling this provider’s resolvers, so every evaluation returns your default at once rather than through a client that will never be there. The underlying Nexus error is on cause. Anything else - a timed-out request, an unreachable network, a server error, an overdue invoice - arrives as a NexusInitError with the reason on cause. The client goes to ERROR, and registering the provider again can clear it.

import { ProviderFatalError } from '@openfeature/web-sdk';
import {
  NexusConfigError,
  NexusInitError,
  NexusUnauthorizedError,
} from '@westyx-nexus/openfeature-web-provider';

try {
  await OpenFeature.setProviderAndWait(provider);
} catch (err) {
  if (err instanceof ProviderFatalError) {
    // nothing to retry - the message and `cause` say what to change
    if (err.cause instanceof NexusConfigError) {
      // an option is unusable; the message names it and the offending value
    } else if (err.cause instanceof NexusUnauthorizedError) {
      // the key was rejected for this endpoint
    }
  } else if (err instanceof NexusInitError) {
    // the first sync could not be completed; another attempt may succeed
  }
}

instanceof answers from a brand rather than from the prototype chain, so it holds for an error raised by any copy of these classes: this package ships an ES module and a CommonJS build, and the Angular, React and Vue SDKs carry copies of their own.

Evaluating flags

const client = OpenFeature.getClient();

// Boolean feature flag
const showBanner = client.getBooleanValue('banner.enabled', false);

// String config
const welcomeText = client.getStringValue('welcome.text', 'Welcome!');

// Number config
const maxItems = client.getNumberValue('list.max_items', 10);

// Object config
const theme = client.getObjectValue('ui.theme', { color: 'blue' });

Use the *Details variants to see why a value was resolved:

const details = client.getBooleanDetails('banner.enabled', false);
// { value: true, reason: 'TARGETING_MATCH', variant: 'true' }

Per-user targeting

Set an evaluation context once the user is known, and every boolean evaluation afterwards is answered for that user - AB tests, cohort rules and percentage rollouts apply.

await OpenFeature.setContext({ targetingKey: user.id, plan: user.plan });

const inBeta = client.getBooleanValue('beta.enabled', false);

A targeting-key change is asynchronous: resolveBooleanEvaluation is synchronous in the OpenFeature Web SDK, so the provider fetches when the context changes rather than during an evaluation. Await setContext.

Targeting covers when the provider fetches, what it sends, what each reason means, and how it behaves when the service is unreachable.

Reacting to live updates

The provider holds an event stream open. When a flag or config actually changes it re-syncs, re-asks the targeted answers, and emits ConfigurationChanged. A stream reconnect on its own does not emit it - nothing about the configuration moved.

import { ProviderEvents } from '@openfeature/web-sdk';

client.addHandler(ProviderEvents.ConfigurationChanged, () => {
  const updatedValue = client.getBooleanValue('banner.enabled', false);
  console.log('banner.enabled is now', updatedValue);
});

Type resolution rules

OpenFeature method	Nexus source	Notes
`getBooleanValue`	Feature flags	Targeted when the context carries a `targetingKey`. An undefined flag is `DEFAULT` + `FLAG_NOT_FOUND` - not the same answer as a flag that is off.
`getStringValue`	Configuration	`TYPE_MISMATCH` if the value is not a string; `FLAG_NOT_FOUND` if absent or `null`.
`getNumberValue`	Configuration	Numbers only, with no coercion: a boolean, a string, an empty array or an integer beyond 2^53 is a `TYPE_MISMATCH` naming what arrived. `FLAG_NOT_FOUND` if absent or `null`.
`getObjectValue`	Configuration	`TYPE_MISMATCH` if the value is not an object or array; `FLAG_NOT_FOUND` if absent or `null`. No `variant` - a composite value has no short identifier to use as one.

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. The scalar getNumberValue answers TYPE_MISMATCH for the same value on purpose. Non-boolean resolutions are never targeted. String, number and object evaluations map to configuration values, and targeted evaluation is a flag concept - there is no such thing as a targeted config value.

Framework examples

Svelte, Solid, Lit, or plain DOM code

import { OpenFeature } from '@openfeature/web-sdk';
import { NexusProvider } from '@westyx-nexus/openfeature-web-provider';

await OpenFeature.setProviderAndWait(
  new NexusProvider({ baseUrl: 'https://blue-ocean-a5rx7.westyx.dev', apiKey: 'wxp_...' }),
);

React (with `@openfeature/react-sdk`)

import { OpenFeatureProvider, useBooleanFlagValue } from '@openfeature/react-sdk';
import { OpenFeature } from '@openfeature/web-sdk';
import { NexusProvider } from '@westyx-nexus/openfeature-web-provider';

await OpenFeature.setProviderAndWait(
  new NexusProvider({ baseUrl: 'https://blue-ocean-a5rx7.westyx.dev', apiKey: 'wxp_...' }),
);

function MyComponent() {
  const showBeta = useBooleanFlagValue('beta.enabled', false);
  return showBeta ? <BetaUI /> : <StableUI />;
}

export function App() {
  return (
    <OpenFeatureProvider>
      <MyComponent />
    </OpenFeatureProvider>
  );
}

An application built on @westyx-nexus/sdk-angular, -react or -vue should use that SDK’s own OpenFeature bridge - Angular, React or Vue - which wraps the client it already has. This package creates and owns one.

Server-side rendering

The provider opens no event stream where the environment cannot hold one, so it is safe to construct during a server-side rendering pass. A connection opened there is never torn down by anything the framework calls, and it holds the request open.

When the stream never connects at all

A stream that fails from the start is a different problem from one that drops: the provider reaches READY, every evaluation is answered from the cache, and the values are correct once and then never change. It looks like a working integration. The client says so once, after it gives up on its first connection:

nexus: live updates could not be established - values refresh on the TTL only.
In a browser this is usually the stream request being blocked: check that the
backend allows this origin and the headers the request carries.

It goes to the logger you configured, or to console.warn if you configured none, so the message reaches the consumer least likely to be looking for it. A connection lost after one succeeded is not reported this way - the stream observer covers that. The usual causes in a browser are CORS-shaped. The stream request carries X-Nexus-API-Key, which is not a CORS-safelisted header, so the browser preflights it: the endpoint has to allow this origin and name that header in Access-Control-Allow-Headers. A blocked preflight is indistinguishable from an unreachable server to the SDK, which is why the message names both.

Stopping the provider

await OpenFeature.close();

This calls onClose(), which releases the event stream, every timer, every listener and the identity the provider was holding.

Notes

Public key only. Use a wxp_... browser key. Secret backend keys (wxs_...) are not accepted.
No secrets. Secret values are never served to a browser key. Only feature flags and configuration are available.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

OpenFeature Web Provider - Usage

Register the provider

Evaluating flags

Per-user targeting

Reacting to live updates

Type resolution rules

Framework examples

Svelte, Solid, Lit, or plain DOM code

React (with `@openfeature/react-sdk`)

Server-side rendering

When the stream never connects at all

Stopping the provider

Notes

​Register the provider

​Evaluating flags

​Per-user targeting

​Reacting to live updates

​Type resolution rules

​Framework examples

​Svelte, Solid, Lit, or plain DOM code

​React (with @openfeature/react-sdk)

​Server-side rendering

​When the stream never connects at all

​Stopping the provider

​Notes

Register the provider

Evaluating flags

Per-user targeting

Reacting to live updates

Type resolution rules

Framework examples

Svelte, Solid, Lit, or plain DOM code

React (with `@openfeature/react-sdk`)

Server-side rendering

When the stream never connects at all

Stopping the provider

Notes