---
url: https://game-engine-io.github.io/enginex-frontend-sdk/guide/getting-started.md
---
# Getting started

## Choose the product

The SDK is split by product. Every app installs the **core** (`@getenginex/sdk`); each of the
operator's products comes in a separate package that uses the core client (the same session, tenant and
configuration):

| The app needs | Install | Track |
| --- | --- | --- |
| sign-up, login and 2FA, password, profile, wallet, PIX deposit and withdrawal, PIX keys, KYC, responsible gaming, notifications | `@getenginex/sdk` | [Core](/core/) |
| everything above + casino (lobby, launch a game, history), bonuses (campaigns, promo codes), missions, loyalty and referrals | `@getenginex/sdk` + `@getenginex/sdk-igaming` | [iGaming](/igaming/) |

```bash
npm i @getenginex/sdk                           # core only
npm i @getenginex/sdk @getenginex/sdk-igaming   # core + casino, bonuses and engagement
```

The core is a *peer dependency* of the product packages: always install it alongside, once. Whoever
does not use the casino does not install (or load) casino code. The steps below apply to any
product; iGaming only adds [step 6](#igaming-products).

## 1. Create the client

Create **one** client per app in the browser and export it:

```ts
// enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'

export const enginex = createEnginexClient({
  locale: 'pt-BR',
  tokenStore: localStorageTokenStore(),
  onSessionExpired: () => location.assign('/login'),
})
```

On the server (SSR, scripts, tests), create one client **per request**, passing the gateway URL and the
operator's domain:

```ts
const enginex = createEnginexClient({
  baseUrl: 'https://gateway.operador.com',
  tenantHost: 'casino.operador.com',
})
```

## 2. Read the operator configuration

```ts
const config = await enginex.config.get()
console.log(config.currency.code, config.paymentMethods.map((m) => m.code))
```

## 3. Log in

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

try {
  const result = await enginex.auth.login({ email, password })
  if (result.status === '2fa_required') {
    // see /flows/login
  }
} catch (e) {
  if (isEnginexError(e, 'INVALID_CREDENTIALS')) showError('Incorrect email or password')
  else throw e
}
```

## 4. React to the session

```ts
enginex.session.subscribe((session) => {
  renderHeader(session.status === 'authenticated')
})
```

## 5. Language and disposal

Change the language at any time with `setLocale` — the next requests already go out with the new
`Accept-Language`:

```ts
enginex.setLocale('en-US')
```

A client **per request** (SSR, scripts, tests) does not need `dispose()` — it is already discarded
along with the rest of the request. A short-lived client outside that case (e.g. a test that creates
several clients), however, should call `dispose()` when done, to release the session subscription on
the `tokenStore` (the `storage` listener, if it is the last one, in the case of `localStorageTokenStore`).
After `dispose()`, every method rejects with `EnginexError` `CONFIGURATION_ERROR`:

```ts
const enginex = createEnginexClient({ baseUrl, tenantHost })
try {
  await enginex.config.get()
} finally {
  enginex.dispose()
}
```

## 6. Products (iGaming) {#igaming-products}

With `@getenginex/sdk-igaming` installed, create the casino and bonus namespaces on top of the **same**
client:

```ts
// enginex.ts
import { createIgaming } from '@getenginex/sdk-igaming'

export const igaming = createIgaming(enginex)

const lobby = await igaming.casino.listGames({ category: 'slots', perPage: 24 })
```

`createIgaming` does not create a session or make a request: the login done with `enginex.auth.login` applies to
the casino, and `enginex.dispose()` also shuts down iGaming. See the [iGaming track](/igaming/).

## Next.js / SSR {#next-js-ssr}

::: tip React and Next.js adapters
With React or Next.js, the adapters do what this section shows by hand: `@getenginex/sdk-react` brings
`EnginexProvider`, `useSession` (the `useSyncExternalStore` below) and query hooks on top of TanStack Query;
`@getenginex/sdk-next` also brings the server's per-request client (`getEnginexServer`, with the tenant taken
from the headers) and the prefetch for `HydrationBoundary`. See the [Frameworks](/frameworks/) track. The rest
of this section applies to those who use the core directly.
:::

`createEnginexClient` never throws on creation, even without `location`, `tenantHost` or an absolute
`baseUrl` — the configuration is only resolved (and memoized) on the first request. This makes it safe to
import a singleton client in a top-level module that also runs during SSR: if it is never
used on the server, nothing breaks; if it is used without the server configuration, the error
(`EnginexError` `CONFIGURATION_ERROR`) only shows up on that first request, without calling `fetch`.

On the client (browser), a singleton in `lib/enginex.ts`, used from a
`'use client'` component:

```tsx
// lib/enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'

export const enginex = createEnginexClient({
  locale: 'pt-BR',
  tokenStore: localStorageTokenStore(),
})
```

```tsx
// app/components/wallet.tsx
'use client'
import { useSyncExternalStore } from 'react'
import { enginex } from '@/lib/enginex'

// Stable snapshot for SSR: there is no localStorage on the server, so the real session is only
// known in the browser. Always using the same object here (instead of a literal `{ status: 'anonymous' }`
// on every call) avoids React's "getServerSnapshot should be cached" warning.
const ANON = { status: 'anonymous' } as const

export function Wallet() {
  const session = useSyncExternalStore(enginex.session.subscribe, enginex.session.get, () => ANON)
  return session.status === 'authenticated' ? <p>Authenticated</p> : null
}
```

Note that you **cannot** use `useState(() => enginex.session.get().status)`: with a
`tokenStore` such as `localStorageTokenStore()`, the server renders `'anonymous'` (there is no
`localStorage` in SSR) and `useState` initializes the browser already as `'authenticated'` for anyone who
was logged in — the markup of the client's first render does not match the server's, and
React discards the hydration (a "hydration mismatch" error). `useSyncExternalStore` solves this: on the
client's first render it also uses `getServerSnapshot` (the `ANON` above), just like the
server, and only switches to the real session after hydrating.

On the server (Server Components, Route Handlers), create one client **per request**, with explicit `baseUrl` and
`tenantHost` — outside the browser there is no `location` to discover them:

```tsx
// app/page.tsx (Server Component)
import { createEnginexClient } from '@getenginex/sdk'

export default async function Page() {
  const enginex = createEnginexClient({
    baseUrl: 'https://gateway.operador.com',
    tenantHost: 'casino.operador.com',
  })
  const config = await enginex.config.get()
  return <main>{config.currency.code}</main>
}
```

## Next steps

* **Core:** [sign-up](/flows/sign-up), [login and 2FA](/flows/login), [PIX deposit](/flows/pix-deposit),
  [withdrawal with OTP](/flows/withdrawal), [PIX keys](/flows/pix-keys) and
  [identity verification (KYC)](/flows/kyc).
* **iGaming:** [casino and launching a game](/igaming/casino) and [bonuses and promo codes](/igaming/bonus).
* **React and Next.js:** [provider and hooks](/frameworks/react), [App Router](/frameworks/next) and the guide
  [Migrating a Next player](/frameworks/migrating-next-player).
* **Reference:** the full API of all packages, generated from the code, in [Reference](/reference/api/index).
