---
url: https://game-engine-io.github.io/enginex-frontend-sdk/guide/installation.md
---
# Installation

```bash
npm i @getenginex/sdk
# or
pnpm add @getenginex/sdk
```

Requirements: browsers with `fetch` and `AbortController` (the SDK depends on neither `AbortSignal.any` nor
`AbortSignal.timeout`), Node 20+, Edge runtimes or Bun. The only dependency is `zod` (4.x).

### `zod`: a single copy {#single-zod-copy}

`zod` is a **regular** dependency (not a *peer*) of the core and the product packages: the package manager
installs one copy for all of them when the version ranges overlap. If the app also uses `zod` at a
version outside that range (e.g. `zod@3`), **two copies** can end up in `node_modules` and in the
bundle. The SDK keeps working (each schema is validated by the `zod` that created it), but the bundle
gets heavier and a global app configuration (`z.config(...)`, e.g. a message locale) applies only to
the app's own copy. To have a single copy, install a single `zod` 4 at the top of the project:

```bash
npm i zod@^4.6.5
npm ls zod # should list a single version
```

## Product packages

`@getenginex/sdk` is the core (client, session, profile, wallet, PIX and realtime). The flows of each
product come in separate packages, installed alongside the core, which is their *peer dependency*.

### Choose the product

```bash
# core only: session, profile, wallet, PIX and realtime
npm i @getenginex/sdk

# iGaming: casino, bonuses and sportsbook FIRST
npm i @getenginex/sdk @getenginex/sdk-igaming

# Predictions: markets, orders, portfolio and live orderbook
npm i @getenginex/sdk @getenginex/sdk-predictions
```

An operator that uses both products installs both product packages, with a single core.
`@getenginex/sdk-igaming` (0.4.0) and `@getenginex/sdk-predictions` (0.2.0) accept core
`>=0.6.0 <1.0.0` (0.5.0 was the first with the `@getenginex/sdk/query` entry). See
[Core](/core/), [iGaming](/igaming/) and [Predictions](/predictions/).

## React and Next.js

For React or Next.js apps with TanStack Query, also install the adapter:

```bash
# React (Vite etc.)
npm i @getenginex/sdk @getenginex/sdk-react @tanstack/react-query

# Next.js (App Router): sdk-next already brings sdk-react
npm i @getenginex/sdk @getenginex/sdk-next @tanstack/react-query
```

Vue uses `@getenginex/sdk-vue` (`npm i @getenginex/sdk @getenginex/sdk-vue @tanstack/vue-query vue`); Svelte
and Solid use the factories from `@getenginex/sdk/query` with the framework's TanStack Query. See the
[Frameworks](/frameworks/) track.

## Proxy to the gateway {#gateway-proxy}

By default the SDK calls `/api/v1/...` on the **same origin** as the page. Forward `/api` to the EngineX
gateway on your server. See the reason in [Tenant and domains](/concepts/tenant).

Next.js (`next.config.ts`):

```ts
export default {
  async rewrites() {
    return [{ source: '/api/:path*', destination: 'https://gateway.operador.com/api/:path*' }]
  },
}
```

Vite (development):

```ts
export default {
  server: { proxy: { '/api': { target: 'https://gateway.operador.com', changeOrigin: true } } },
}
```

Nginx:

```nginx
location /api/ {
  proxy_pass https://gateway.operador.com;
  proxy_set_header Host gateway.operador.com;
}
```

## Local development {#local-development}

With the Vite proxy (or `next dev`), the page runs on `localhost:5173` and the SDK sends that host as the
operator identifier (`X-Original-Host: localhost:5173`), which does not belong to any operator. In
development, provide the operator's domain with `tenantHost`:

```ts
import { createEnginexClient } from '@getenginex/sdk'

export const enginex = createEnginexClient({
  tenantHost: import.meta.env.VITE_ENGINEX_TENANT, // e.g. casino.operador.com (dev only)
})
```

```bash
# .env.development
VITE_ENGINEX_TENANT=casino.operador.com
```

In production **do not set** the variable (the value must stay `undefined`, not an empty string): without `tenantHost` the SDK uses the site's real domain
(`location.host`). `tenantHost` applies to same-origin calls, that is, through the `/api` proxy.
If something does not work, see [Troubleshooting](/guide/troubleshooting).

## Examples {#examples}

The SDK repository has three small apps in `examples/`, each a standalone project (outside the pnpm
workspace) that installs the packages as a real app would:

| Example | What it shows |
| --- | --- |
| `examples/vanilla-vite` | `@getenginex/sdk` with Vite and plain TypeScript: a client with `createMockFetch`, the operator configuration and a mocked login, no framework |
| `examples/vue-vite` | `@getenginex/sdk-vue` with Vue 3: login, balance with `useEnginexQuery`, PIX deposit with `useEnginexMutation` and the balance updated by `useRealtimeSync`, all in mock mode (`createMockFetch` and `createMockRealtime`) |
| `examples/next` | `@getenginex/sdk-next` with the App Router: `getEnginexServer` and `prefetchEnginex` in the layout, hydration, login, balance, PIX deposit, realtime and the `withEnginex` rewrite; runs against a gateway or in mock mode |

From a checkout of the repository, each one runs like any npm project:

```bash
cd examples/vue-vite
npm install
npm run dev
```

Until the packages are published on npm, `npm install` inside an example does not resolve them. To check
them before that, use the consumer tests: they pack the repository's packages, install the local tarballs in
each example and **build** it (type check and production build; `examples/next` runs `next build`). They do not
start a dev server: to click through an example, run it with `npm run dev` once the packages are on npm.

```bash
pnpm install && pnpm build
pnpm test:consumers                          # every consumer, the three examples included
ENGINEX_CONSUMERS=next pnpm test:consumers   # only one: vanilla-vite, vue-vite or next
```

`examples/next` has two modes: with `NEXT_PUBLIC_ENGINEX_MOCK=1` the browser client uses the mocks (log in with
`ana@exemplo.com` / `Senha@123`); with `ENGINEX_GATEWAY_URL`, the server reads the gateway and the tenant is the
request's `host`:

```bash
# examples/next, mock mode (no gateway)
NEXT_PUBLIC_ENGINEX_MOCK=1 npm run dev

# examples/next, with a gateway
ENGINEX_GATEWAY_URL=https://gateway.operador.com npm run build
ENGINEX_GATEWAY_URL=https://gateway.operador.com npm start
```
