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

# React SDK

> Official React SDK for Westyx Nexus - hooks backed by useSyncExternalStore, NexusProvider.

Official React SDK for [Westyx Nexus](https://westyx.dev) - the centralised secrets, feature flags, and config service.

```tsx theme={null}
import { NexusProvider, useConfig, useFlag } from '@westyx-nexus/sdk-react';

function App() {
  const banner = useConfig<string>('public.banner');
  const isV2   = useFlag('checkout.v2', false);
  return <h1>{isV2 ? 'Checkout v2' : 'Checkout'} - {banner}</h1>;
}

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

## What's new in v0.10.0

* Version alignment across the Westyx Nexus SDK suite.

## What's new in v0.8.0

* **`@westyx-nexus/openfeature-provider-react`** - OpenFeature bridge provider wrapping an existing `NexusClient`. Emits `ConfigurationChanged` on every cache update; exposes flags as boolean evaluations and configs as string/number/object evaluations.

## What's new in v0.4.1

* **Security improvements** - exception messages contain only HTTP status codes; response bodies are never exposed in errors.
* **Fetch-based SSE** - the live-update stream now uses `fetch` streaming. The API key travels as a header, not a URL query parameter.
* **CI improvements** - tests run on every MR and `main` push; publish restricted to `main`-branch tags.

## What's new in v0.4.0

* **`NexusQuarantinedError`** - new typed error on 429 with quarantine body; sync and stream both pause until `expiresAt`.
* **`onQuarantined(reason, expiresAt)` observer callback** - fires from both sync and stream paths.
* **Path prefix change** - all API paths now use `/v1/`. Update `baseUrl` to `<slug>.westyx.dev`.

## What's new in v0.3.1

* **5xx sync hardening** - `/sync` 5xx responses now retry with exponential backoff (1 s to 30 s capped) instead of failing silently until the next TTL tick. During the wait the SDK emits `FALLBACK_REASON_TRANSPORT` on the stream observer.
* **429 SSE pre-flight probe** - `connectStream()` now runs a `fetch` pre-flight against the stream URL before opening `EventSource`. On HTTP 429 the SDK parses `Retry-After` (clamped to `[5 s, 300 s]`, default 5 s on miss), emits `FALLBACK_REASON_RATE_LIMITED`, and re-attempts the connect after the indicated delay.
* **New constant** - `FALLBACK_REASON_TRANSPORT` (`'transport'`) is now exported alongside `FALLBACK_REASON_MAX_ERRORS` and `FALLBACK_REASON_RATE_LIMITED`.

## Highlights

* **React 18+** - single package, zero external runtime dependencies (uses platform `fetch`)
* **`NexusProvider` blocking initial sync** - children never render against an empty cache
* **Hooks API** backed by `useSyncExternalStore` - components re-render automatically on every cache change
* **Thread-safe TTL cache** with atomic snapshot replacement and ETag/304 support
* **SSE live updates** - propagates remote changes within milliseconds; falls back to TTL polling after 3 transport errors
* **public-key enforcement** - browser SDKs must use a public key; secret keys are rejected at runtime
* **Stream observer hooks** *(v0.2.0)* - structured callbacks for SSE lifecycle events
* **Service-kind-aware secret access** *(v0.2.0)* - `useSecret()` returns `undefined` on frontend services automatically

<Warning>
  Browser SDKs must use a `wxp_...` (public) key. Never embed secret keys (`wxs_...`) in browser code.
</Warning>

## Package

Hosted on the [GitLab npm Package Registry](https://gitlab.com/westyx/nexus/sdk/react/-/packages). Install:

```sh theme={null}
npm install @westyx-nexus/sdk-react
```

Latest release: **v0.10.0** *(2026-07-05 - version alignment across the Westyx Nexus SDK suite)*.

## Pages

| Page                                 | Description                                                              |
| ------------------------------------ | ------------------------------------------------------------------------ |
| [Installation](installation)         | Register the GitLab npm registry and install                             |
| [Configuration](configuration)       | `NexusConfig` field reference + provider props                           |
| [API reference](api-reference)       | Every hook and imperative method                                         |
| [Error handling](error-handling)     | Error hierarchy, error boundaries, `onError` render prop                 |
| [SSE live updates](sse-live-updates) | How live propagation works in the browser                                |
| [Stream observer](stream-observer)   | `NexusStreamObserver` reference                                          |
| [OpenFeature](openfeature)           | OpenFeature bridge provider (`@westyx-nexus/openfeature-provider-react`) |