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

# Vue SDK - Installation

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

The `@westyx-nexus/sdk-vue` package is hosted on the [GitLab npm Package Registry](https://gitlab.com/westyx/nexus/sdk/vuejs/-/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/81979879/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-vue
```

Pin to a specific version:

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

## Requirements

* **Vue 3.3** or newer (Composition API - Options API is not supported)
* A modern browser environment with `fetch` streaming support - `ReadableStream` response bodies (Chrome, Firefox, Safari, Edge - all evergreens)
* TypeScript users: 5.0+ for full type compatibility (peer of Vue 3.3 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-vue';

const apiKey: string = import.meta.env.VITE_NEXUS_API_KEY;
assertPublicKey(apiKey);  // narrows to PublicApiKey, throws if not wxp_
```

## Importing

The package exposes both ESM and CJS builds:

<CodeGroup>
  ```ts title="ES Modules / TypeScript / Vite / Nuxt" theme={null}
  import { provideNexus } from '@westyx-nexus/sdk-vue';
  ```

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

## SSR / Nuxt

The fetch-based SSE stream is browser-only (the SDK skips it during SSR). In Nuxt 3, register the SDK in a **client-only plugin**:

```ts theme={null}
// plugins/nexus.client.ts
import { provideNexus } from '@westyx-nexus/sdk-vue';

export default defineNuxtPlugin(async (nuxtApp) => {
  await provideNexus(nuxtApp.vueApp, {
    baseUrl: useRuntimeConfig().public.nexusUrl,
    apiKey:  useRuntimeConfig().public.nexusApiKey,
  });
});
```

The `.client.ts` suffix tells Nuxt to skip this plugin on the server, so SSR doesn't try to open the stream.

## 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-vue'`** - 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.