React SDK - Configuration

The SDK is configured via the NexusConfig interface, passed to <NexusProvider config={...}>. The provider also accepts a few props that control its render lifecycle.

`NexusConfig`

<NexusProvider config={{
  baseUrl: 'https://<slug>.westyx.dev',  // required
  apiKey:  'wxp_...',                // required
  ttlMs:   60_000,                       // optional, default 60 000 ms
  logger:  myLogger,                     // optional
}}>

Field	Type	Default	Description
`baseUrl`	`string`	-	Full service URL, e.g. `https://<slug>.westyx.dev`. The slug embedded in the host is also used as the `Host` header (Double-Gate requirement).
`apiKey`	`string`	-	Raw `wxp_...` key. Sent in the `X-Nexus-API-Key` header on both `/v1/sync` and `/v1/stream`. The SDK uses fetch-based SSE (not the browser `EventSource` API), so the key travels as a header - never as a `?key=...` query parameter. (header-only since v0.4.1)
`ttlMs`	`number`	`60_000`	Local cache TTL in milliseconds. After this elapses, the next read triggers a one-shot background refresh while still serving the stale cache.
`logger`	`NexusLogger`	`NOOP_LOGGER`	Optional diagnostic logger. Defaults to a no-op (silent).
`streamObserver`	`NexusStreamObserver?`	`undefined`	(v0.2.0) Optional structured-callback observer for SSE lifecycle events. See Stream observer.
`sseReconnectCooldown`	`number \| number[]`	`undefined`	Schedule for reconnecting SSE after falling back to TTL polling. Unit: minutes. `undefined` = default `[5, 10, 20, 40, 60]` min exponential. Single number = fixed interval. Array = custom schedule (stays at last value). (v0.6.0)

`NexusProvider` props

Prop	Type	Description
`config`	`NexusConfig`	Required. Passed to `NexusClient.create()`.
`children`	`ReactNode`	Rendered after the initial sync resolves.
`loadingFallback`	`ReactNode`	Optional. Rendered while the initial sync is in flight. Defaults to `null`.
`onError`	`(error: Error) => ReactNode`	Optional. Called when the initial sync fails. If omitted, the error is thrown so an Error Boundary can catch it.

API key types

Prefix	Access	Browser-safe?
`wxs_...`	Full - all configs, all secrets, all flags	rejected at runtime by the SDK
`wxp_...`	Restricted - public configs and flags; `useSecret()` always returns `undefined`	yes

Browser SDKs must use a wxp_... key. The SDK enforces this in three places:

PublicApiKey branded type - when typed strictly, TypeScript prevents passing a plain string without assertPublicKey()
Runtime guard - throws Error('Browser SDKs require a public key (wxp_...)') before any network call
Backend enforcement - a request carrying an wxs_... key in the X-Nexus-API-Key header against a browser/public surface is rejected with 400 Bad Request

import { assertPublicKey } from '@westyx-nexus/sdk-react';

const apiKey = import.meta.env.VITE_NEXUS_API_KEY;
assertPublicKey(apiKey);  // narrows to PublicApiKey

<NexusProvider config={{ baseUrl: '...', apiKey }}>

Where to keep the API key

Anywhere your existing build pipeline injects environment-specific config - typically .env files for Vite / CRA, or NEXT_PUBLIC_* variables for Next.js. wxp_... keys are intended to be public, so embedding them in the built JavaScript bundle is fine.

<NexusProvider config={{
  baseUrl: import.meta.env.VITE_NEXUS_URL,
  apiKey:  import.meta.env.VITE_NEXUS_API_KEY,
}}>

<NexusProvider config={{
  baseUrl: process.env.NEXT_PUBLIC_NEXUS_URL!,
  apiKey:  process.env.NEXT_PUBLIC_NEXUS_API_KEY!,
}}>

Choosing the TTL

The TTL is a tradeoff between staleness window and redundant network traffic. With SSE enabled (the default), changes propagate in milliseconds regardless of the TTL - the TTL only matters as a safety net when the stream falls back.

Use case	Suggested `ttlMs`
Frequently-changing flags, latency-sensitive	30 000 (30 s)
Standard configs with SSE	60 000 (default)
Boot-time only, rarely re-checked	600 000 (10 min)

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

React SDK - Configuration

`NexusConfig`

`NexusProvider` props

API key types

Where to keep the API key

Choosing the TTL

​NexusConfig

​NexusProvider props

​API key types

​Where to keep the API key

​Choosing the TTL

`NexusConfig`

`NexusProvider` props

API key types

Where to keep the API key

Choosing the TTL