> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenFeature Web Provider

> OpenFeature Web SDK provider for Westyx Nexus - per-user targeted feature flags through the OpenFeature standard.

OpenFeature Web SDK provider for [Westyx Nexus](https://westyx.dev) - feature flags and configuration through the [OpenFeature](https://openfeature.dev) standard browser API, for a browser application with no Nexus framework SDK.

```ts theme={null}
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_...',
  }),
);

const client = OpenFeature.getClient();

// once the user is known
await OpenFeature.setContext({ targetingKey: user.id, plan: user.plan });

// answered for this user
const showBanner = client.getBooleanValue('banner.enabled', false);
```

## What's new in v0.19.0

* **HTTP 423 `service_locked`:** exports `NexusServiceLockedError`, stops SSE reconnects immediately on `423`, halts background sync retries, and suppresses repeated `evaluate-ab` calls while locked.

## What's new in v0.18.2

* **A switched-off environment is not asked again.** While the environment is switched off in the console, the provider keeps the targeted values it already had and sends no `evaluate-ab` request - for any context - for the add-on suppression window (five minutes by default), with one warning; the first successful evaluation clears it.

## What's new in v0.18.1

* **An idle page keeps refreshing while the live stream is down.** The client reads its cache once per TTL on its own, so `ConfigurationChanged` reaches a page that evaluates nothing. See [Usage](https://docs.westyx.dev/sdks/openfeature-web-provider/usage.md#reacting-to-live-updates).

## What's new in v0.18.0

* **A switched-off environment is reported by name.** When the project switches the service's environment off, the server answers `403 environment_disabled`: at start-up it arrives as `NexusEnvironmentDisabledError` on `NexusInitError.cause` and the provider goes to `ERROR`; on a running provider the refresh waits five minutes between attempts and the stream moves to its polling schedule until the environment is switched on. See [Usage](https://docs.westyx.dev/sdks/openfeature-web-provider/usage.md#errors).
* **`NexusApiError`** carries `status` and `code` for any status with no dedicated class.
* CI runs the suite on Node 20, 22, 24 and 26.

## What's new in v0.17.0

* **Local development without a key.** With neither `baseUrl` nor `apiKey`, the provider takes the endpoint and a Developer WIF session from `westyx dev run` through the dev server - see [Local development](https://docs.westyx.dev/sdks/openfeature-web-provider/usage.md#local-development).
* `NexusDevSessionError` says why the developer session could not be obtained.

## What's new in v0.16.0

* **Breaking: `NexusPublicKeyError` removed.** It was raised only by `getSecret()`, which the shared browser core removed: a browser client always holds a public key, and the backend never sends a secret to one. No change needed unless your code caught this error type.

## What's new in v0.15.0

* **A live stream that never connects is reported.** When the client gives up before its first successful connection it says so once - through the logger you configured, or on `console.warn` if you configured none. Evaluations keep being answered from the cache, refreshed on the TTL, so without this the provider stays `READY` and its values simply stop changing. A connection lost *after* connecting is reported by the stream observer instead. See [Usage](https://docs.westyx.dev/sdks/openfeature-web-provider/usage.md).
* **The stream request carries only the API key and `Accept`.** Both are all the server needs, which is one fewer name a deployment's CORS configuration has to allow.

## What's new in v0.14.0

* **A start-up failure that no retry can fix reports `PROVIDER_FATAL`.** A rejected API key, a base URL naming no service, and a configuration value the client will not accept leave the client in `FATAL`, where the SDK stops calling this provider and every evaluation returns your default at once. A timeout, an unreachable network, a server error and an overdue invoice stay recoverable, and registering the provider again can clear them. See [Usage](https://docs.westyx.dev/sdks/openfeature-web-provider/usage.md).
* **`instanceof` recognises an error raised by any copy of these classes.** This package ships an ES module and a CommonJS build, and the framework SDKs carry copies of the same hierarchy, so an application can hold more than one class object per error type. The operator answers from a brand and gives one answer.
* **`NexusNotFoundError` is exported**, which is what a base URL naming no service puts on the failure's `cause`.
* **The configuration you pass is copied at construction**, so mutating that object afterwards - or reusing one across two providers - cannot change which endpoint or which key a provider uses.

## What's new in v0.13.0

* **A composite (object or array) resolution carries an integer beyond
  `Number.MAX_SAFE_INTEGER` as its exact decimal string** - at any depth, in objects and
  arrays alike, so the resolved value survives `JSON.stringify`. Ordinary numbers are
  untouched, and the scalar number resolution still answers `TYPE_MISMATCH` for the
  same value.

## What's new in v0.12.0

* **Per-user targeting.** A boolean evaluation whose context carries a `targetingKey` answers with the flag's value for that user, so AB tests, cohort rules and percentage rollouts apply, and reports `TARGETING_MATCH`. One round trip covers every flag in the snapshot. See [Targeting](https://docs.westyx.dev/sdks/openfeature-web-provider/targeting.md).
* **The same client as the framework SDKs.** The provider compiles in the browser client the Angular, React and Vue SDKs use, so it behaves identically: request deadlines, ETag-aware sync, a liveness deadline on the event stream, lossless JSON decoding, and reconnection after any close.
* **`endpoint` is now `baseUrl`** - a breaking configuration change.
* An unknown flag reports `FLAG_NOT_FOUND` rather than a successful resolution, and a number evaluation no longer coerces a boolean, an empty string or an empty array into a number.

The version jumps from `0.8.0` to `0.12.0` to sit with the other eleven OpenFeature bridges, which all ship this same contract at `0.12.x`.

## Highlights

* **Framework-agnostic** - any browser TypeScript or JavaScript application: Svelte, Solid, Lit, or plain DOM code.
* **OpenFeature standard** - code against the vendor-neutral `OpenFeature.getClient()` API and swap providers without rewriting evaluation code.
* **Per-user targeted booleans** - one batched round trip per evaluation context, then every evaluation is a synchronous local read.
* **Live updates** - the provider holds an event stream open and emits `ConfigurationChanged` when a flag or config actually changes.
* **Honest failure behaviour** - a transport failure serves the last known value as `STALE`, never the caller's default.
* **Public key only** - `wxp_...` browser keys; a secret key is rejected when the provider initialises.

> [!WARNING]
>
> Browser SDKs must use a `wxp_...` (public) key. Never embed secret keys (`wxs_...`) in browser code.

> [!NOTE]
>
> Already using `@westyx-nexus/sdk-angular`, `-react` or `-vue`? Use that SDK's own OpenFeature bridge instead. It wraps the client the application already has, where this package creates and owns one - so next to a framework SDK it would open a second connection and keep a second cache.

## Package

```bash theme={null}
npm install @westyx-nexus/openfeature-web-provider @openfeature/web-sdk
```

Latest release: **v0.19.0** *(2026-11-19 - HTTP 423 `service_locked` support and immediate SSE stop)*.

## Pages

| Page | Description |
| - | - |
| [Installation](https://docs.westyx.dev/sdks/openfeature-web-provider/installation.md) | Install, registry, requirements and API keys |
| [Usage](https://docs.westyx.dev/sdks/openfeature-web-provider/usage.md) | Registering the provider, every resolve type, live updates |
| [Targeting](https://docs.westyx.dev/sdks/openfeature-web-provider/targeting.md) | Per-user evaluation: when it fetches, what it sends, what each reason means |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.