> ## 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 - Installation

> Register the GitLab npm registry and install the React SDK.

The `@westyx-nexus/sdk-react` package is hosted on the [GitLab npm Package Registry](https://gitlab.com/westyx/nexus/sdk/react/-/packages). It is **public** - no token is required to install.

## 1. Configure npm to look at the registry

Add (or merge) the following to your project's `.npmrc`:

```ini theme={null}
@westyx-nexus:registry=https://gitlab.com/api/v4/projects/81979839/packages/npm/
```

<Info>
  Commit the `.npmrc` to source control. It contains no credentials - every developer on the team automatically picks up the right registry.
</Info>

## 2. Install the package

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

Pin to a specific version:

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

## Requirements

* **React 18.0** or newer (uses `useSyncExternalStore` - React 18 baseline)
* A modern browser environment with `fetch` streaming support - `ReadableStream` response bodies (Chrome, Firefox, Safari, Edge - all evergreens)
* TypeScript users: 4.7+ for full type compatibility (peer of React 18 typings)

## Use a public API key

<Warning>
  Browser SDKs must use a `wxp_...` (public) key. Secret keys (`wxs_...`) are rejected at runtime.

  The API key is sent in the `X-Nexus-API-Key` header on every request, including the SSE `/stream` connection - the SDK uses fetch-based streaming, not the browser `EventSource` API, so the key never appears in the URL, server access logs, or browser history.
</Warning>

The SDK enforces this via:

1. A **branded TypeScript type** (`PublicApiKey`) - gives you a compile-time hint when typing strictly
2. A **runtime guard** in the SDK constructor - throws a descriptive error before any network call
3. A **backend reject** - a request carrying an `wxs_...` key against a browser/public surface returns `400 Bad Request`

```ts theme={null}
import { assertPublicKey } from '@westyx-nexus/sdk-react';

const apiKey: string = process.env.REACT_APP_NEXUS_API_KEY!;
assertPublicKey(apiKey);  // narrows to PublicApiKey, throws if not wxp_
```

## Importing

The package exposes both ESM and CJS builds:

<CodeGroup>
  ```tsx title="ES Modules / TypeScript / Vite / Next.js" theme={null}
  import { NexusProvider } from '@westyx-nexus/sdk-react';
  ```

  ```js title="CommonJS (rare for React projects)" theme={null}
  const { NexusProvider } = require('@westyx-nexus/sdk-react');
  ```
</CodeGroup>

The package's `exports` map handles the format selection automatically.

## SSR / Next.js

`NexusProvider` opens a fetch-based SSE stream on mount, which is browser-only (the SDK skips it during SSR). Use `'use client'` (Next.js App Router) on the file containing `NexusProvider`, or render it under a client-only boundary.

## Verifying connectivity

Before writing any code, confirm your endpoint and API key work with a plain `curl`:

```sh theme={null}
curl -s \
  -H "X-Nexus-API-Key: wxp_..." \
  https://your-service.westyx.dev/v1/sync
```

A valid response returns a JSON snapshot with your `configs` and `flags` (browser SDKs use public keys - secrets are never included). An `HTTP 401` means the key is wrong; `HTTP 404` means the slug is wrong.

## Troubleshooting

* **`Could not resolve '@westyx-nexus/sdk-react'`** - your `.npmrc` is not picked up. Confirm it's at the project root next to `package.json`, and check `npm config get registry @westyx-nexus`.
* **`401 Unauthorized` when running `npm install`** - the registry might be configured with an old path. Switch to the numeric-ID variant above.
* **`Browser SDKs require a public key`** at runtime - replace your `wxs_...` key with a `wxp_...` key from the same service in the Westyx Nexus admin UI.