React SDK - API Reference

Every public symbol exported by @westyx-nexus/sdk-react. Hooks are the primary surface; the imperative NexusClient is exposed via useNexus() for advanced use cases.

Provider

`<NexusProvider config={...}>`

Top-level provider that creates the NexusClient instance, performs the blocking initial sync, and connects the SSE stream.

<NexusProvider config={config}>
  <App />
</NexusProvider>

Prop	Type	Description
`config`	`NexusConfig`	Required. See Configuration.
`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.

Hooks

`useConfig<T>(key: string): T | undefined`

Read a config value. Returns the resolved value as T (the wire-decoded JSON), or undefined when the key is absent.

const port    = useConfig<number>('server.port');
const banner  = useConfig<string>('public.banner');
const tags    = useConfig<string[]>('app.tags');

public-key clients only see configs that are public (filtering is server-side).

`useFlag(key: string, defaultValue?: boolean): boolean`

Read a flag value. Returns defaultValue (default false) when the key is absent.

const isOn = useFlag('checkout.v2');           // false if missing
const isOn = useFlag('checkout.v2', true);     // true if missing

`useEvaluateAB(): (keys, userId, attributes?) => Promise<Record<string, boolean>>`

Returns a stable callback that evaluates one or more feature flags through the AB Testing endpoint (POST /v1/flags/evaluate-ab). The callback identity is stable across renders unless the underlying client changes. Unlike useFlag, every invocation hits the network - results are not cached, because targeting rules and rollout buckets depend on the supplied userId / attributes.

import { useEffect, useState } from 'react';
import { useEvaluateAB, NexusAbAddonNotAvailableError } from '@westyx-nexus/sdk-react';

function CheckoutGate({ user }: { user: { id: string; plan: string } }) {
  const evaluateAB = useEvaluateAB();
  const [showV2, setShowV2] = useState(false);

  useEffect(() => {
    evaluateAB(['checkout.v2'], user.id, { plan: user.plan })
      .then((results) => setShowV2(results['checkout.v2'] === true))
      .catch((err) => {
        if (err instanceof NexusAbAddonNotAvailableError) {
          setShowV2(false);   // add-on disabled - fall back to control
        }
      });
  }, [evaluateAB, user]);

  return showV2 ? <CheckoutV2 /> : <Checkout />;
}

Rejected promise errors:

Error	When
`NexusAbAddonNotAvailableError`	HTTP 403 - the AB Testing add-on is not active for the tenant.
`NexusUnauthorizedError`	HTTP 401 - invalid API key or slug/key mismatch.
`NexusBillingError`	HTTP 402 - tenant has overdue invoices.
`NexusNotFoundError`	HTTP 404 - unknown subdomain or missing endpoint.

`useSecret(key: string): string | undefined`

Read a secret value. Returns undefined if the client uses a public key, or if the key is missing - it never throws (this is the React-friendly variant of the imperative getSecret).

const stripeKey = useSecret('stripe.key');

In browser apps you’ll typically be using a public key, so useSecret always returns undefined.

`useNexusSyncedAt(): Date`

Last successful sync timestamp. Useful for “last refreshed N seconds ago” UIs.

const syncedAt = useNexusSyncedAt();
return <small>Last refreshed: {syncedAt.toLocaleTimeString()}</small>;

`useNexusSync(): () => Promise<void>`

Returns a stable function that triggers a manual sync. Use sparingly - the SDK syncs automatically.

const sync = useNexusSync();

return <button onClick={() => sync()}>Refresh config</button>;

`useNexusStreamStatus(): { connected: boolean }`

Reactive SSE state. Useful for surfacing a “live” / “polling” indicator.

const { connected } = useNexusStreamStatus();
return <span>{connected ? 'Live' : 'Polling'}</span>;

`useNexus(): NexusClient`

Escape hatch - returns the underlying NexusClient instance for advanced use. Reads via this client are not reactive (don’t subscribe to the cache). Use the typed hooks above unless you have a specific reason.

Imperative `NexusClient` (rarely needed)

const nexus = useNexus();

// Read API (non-reactive - for one-shot lookups)
nexus.getConfig<T>(key)        // T | undefined
nexus.getFlag(key, default?)   // boolean
nexus.getSecret(key)           // throws NexusPublicKeyError or NexusSecretNotFoundError
nexus.getAllConfigs()          // Map<string, unknown>
nexus.getAllFlags()            // Map<string, boolean>

// AB Testing (v0.3.0) - always hits the network, never cached
await nexus.evaluateAB(keys, userId, attributes?);  // Promise<Record<string, boolean>>

// Lifecycle
await nexus.sync();            // force a sync now, bypassing the TTL
nexus.connectStream();         // start SSE (idempotent)
nexus.disconnectStream();      // stop SSE
nexus.subscribe(listener);     // listener called on every snapshot replacement

// Metadata
nexus.keyType;                 // 'sk' | 'pk' - always 'pk' in browsers
nexus.syncedAt;                // Date
nexus.streamConnected;         // boolean
nexus.billingOverdue;          // boolean - true after the server returned HTTP 402

Error types

import {
  NexusError,                       // base class
  NexusInitError,                   // initial sync failure (cause carries detail)
  NexusUnauthorizedError,           // HTTP 401
  NexusBillingError,                // HTTP 402 - tenant has overdue invoices
  NexusAbAddonNotAvailableError,    // HTTP 403 from evaluateAB - add-on disabled
  NexusQuarantinedError,            // HTTP 429 quarantine - reason + expiresAt (v0.4.0)
  NexusNotFoundError,               // HTTP 404
  NexusPublicKeyError,              // imperative getSecret with public key
  NexusServiceKindMismatchError,    // imperative getSecret on kind=frontend service
  NexusSecretNotFoundError,         // imperative getSecret with unknown key
} from '@westyx-nexus/sdk-react';

NexusInitError is the only one fired during the provider’s normal flow. The hook useSecret is non-throwing (returns undefined); the imperative getSecret throws.

Type helpers

import {
  PublicApiKey,        // branded string type - narrows public keys at compile time
  assertPublicKey,     // runtime guard - throws if key is not wxp_
} from '@westyx-nexus/sdk-react';

const raw: string = import.meta.env.VITE_NEXUS_API_KEY;
assertPublicKey(raw);  // raw is now PublicApiKey

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

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

React SDK - API Reference

Provider

`<NexusProvider config={...}>`

Hooks

`useConfig<T>(key: string): T | undefined`

`useFlag(key: string, defaultValue?: boolean): boolean`

`useEvaluateAB(): (keys, userId, attributes?) => Promise<Record<string, boolean>>`

`useSecret(key: string): string | undefined`

`useNexusSyncedAt(): Date`

`useNexusSync(): () => Promise<void>`

`useNexusStreamStatus(): { connected: boolean }`

`useNexus(): NexusClient`

Imperative `NexusClient` (rarely needed)

Error types

Type helpers

​Provider

​<NexusProvider config={...}>

​Hooks

​useConfig<T>(key: string): T | undefined

​useFlag(key: string, defaultValue?: boolean): boolean

​useEvaluateAB(): (keys, userId, attributes?) => Promise<Record<string, boolean>>

​useSecret(key: string): string | undefined

​useNexusSyncedAt(): Date

​useNexusSync(): () => Promise<void>

​useNexusStreamStatus(): { connected: boolean }

​useNexus(): NexusClient

​Imperative NexusClient (rarely needed)

​Error types

​Type helpers

Provider

`<NexusProvider config={...}>`

Hooks

`useConfig<T>(key: string): T | undefined`

`useFlag(key: string, defaultValue?: boolean): boolean`

`useEvaluateAB(): (keys, userId, attributes?) => Promise<Record<string, boolean>>`

`useSecret(key: string): string | undefined`

`useNexusSyncedAt(): Date`

`useNexusSync(): () => Promise<void>`

`useNexusStreamStatus(): { connected: boolean }`

`useNexus(): NexusClient`

Imperative `NexusClient` (rarely needed)

Error types

Type helpers