---
url: https://game-engine-io.github.io/enginex-frontend-sdk/frameworks/vue.md
---
# Vue

`@getenginex/sdk-vue` connects the core client and `@tanstack/vue-query` v5 to a Vue 3 app: reactive session,
typed queries and mutations, invalidation after every write, cache cleanup on user switch and
realtime. The package runs in the browser. In Nuxt, use it client-side only (see [Nuxt](#nuxt-client-only)).

```bash
npm i @getenginex/sdk @getenginex/sdk-vue @tanstack/vue-query vue
```

Peers: `vue >=3.5`, `@tanstack/vue-query ^5` and `@getenginex/sdk >=0.6.0 <1.0.0`. A complete project, in
mock mode (no gateway), is at
[`examples/vue-vite`](/guide/installation#examples).

## Plugin

Create the core client **once**, outside the components, and install `EnginexPlugin`:

```ts
// main.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
import { EnginexPlugin } from '@getenginex/sdk-vue'
import { createApp } from 'vue'
import App from './App.vue'

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

createApp(App).use(EnginexPlugin, { client: enginex }).mount('#app')
```

The plugin installs TanStack's `VueQueryPlugin`, provides the client to the composables and, when the session's user
changes, **removes** from the cache everything under `['enginex', 'user']` (see [User switch](#user-switch)).
The session subscription is released on `app.unmount()`.

### With the app's `QueryClient`

Without a `queryClient`, the plugin creates one per app (never a module singleton), with a 60 s `staleTime` on
queries. If the app already has a `QueryClient`, pass it: it is used as-is, without changing any option.

```ts
import { QueryClient } from '@tanstack/vue-query'

const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: 5 * 60_000, retry: 1, refetchOnWindowFocus: false } },
})

createApp(App).use(EnginexPlugin, { client: enginex, queryClient }).mount('#app')
```

### If the app already installs `VueQueryPlugin`

With `installVueQuery: false` the plugin does not install `VueQueryPlugin`, and `queryClient` becomes
**required**: it must be exactly the same one the app installed in `VueQueryPlugin`. The plugin throws an error
if it is missing. With two different `QueryClient`s, the cache cleanup on user switch and the invalidation of
mutations would act on one cache while the queries read from another; that is why the plugin (on install) and the
composables (in `setup`) throw an error when the app's `VueQueryPlugin` uses another `QueryClient`. This also applies
without `installVueQuery: false`: if the app already installed `VueQueryPlugin`, pass the same `queryClient` to
`EnginexPlugin`.

```ts
createApp(App)
  .use(VueQueryPlugin, { queryClient })
  .use(EnginexPlugin, { client: enginex, queryClient, installVueQuery: false })
  .mount('#app')
```

`client` and `queryClient` must be stable. To switch tenants, create another app (or remount it).

## Session

```vue
<script setup lang="ts">
import { useEnginex, useSession } from '@getenginex/sdk-vue'

const session = useSession()
const enginex = useEnginex()
</script>

<template>
  <button v-if="session.status === 'authenticated'" @click="enginex.auth.logout()">Log out</button>
  <LoginButton v-else />
</template>
```

* `useSession()` returns a read-only ref (`shallowRef`) over `client.session`; the reference only changes
  when the session changes (refreshing the same user's tokens does not replace it). The subscription is released when the
  component's scope ends. In the template the ref is unwrapped (`session.status`); in the `<script>`, use
  `session.value`.
* `useEnginex()` returns the plugin's client (throws in an app without `EnginexPlugin`).

### User keys: `useUserKey`

To invalidate or read the signed-in player's data from the cache, `useUserKey(namespace?, method?)` returns a
`computed` with the `['enginex', 'user', userId, namespace?, method?]` prefix for the current session, or `null` with no
session. `namespace` and `method` accept a value, ref or getter:

```ts
import { useUserKey } from '@getenginex/sdk-vue'
import { useQueryClient } from '@tanstack/vue-query'

const queryClient = useQueryClient()
const walletKey = useUserKey('wallet') // ['enginex', 'user', userId, 'wallet']
const refresh = () => walletKey.value && queryClient.invalidateQueries({ queryKey: walletKey.value })
```

Outside a component, `enginexKeys.user(userId, namespace, method?)` (from `@getenginex/sdk/query`) builds the
same key. For an exact `setQueryData`, use the key from the factory itself (`q.wallet.getBalance().queryKey`).

### User switch {#user-switch}

When the session's user changes (logout, login, or login with a different `sub`), the plugin **removes** from the cache everything
under `['enginex', 'user']`: one player's data is never served to another. The comparison uses `status` and
`userId`, so refreshing the same user's tokens clears nothing. `['enginex', 'public']` and the
app's keys are left as they are. If the app has its own keys with player data, clear them yourself (e.g. with a
`watch` over `useSession()`).

## Queries

```vue
<script setup lang="ts">
import { useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-vue'

const q = useEnginexQueries()
const { data: balance, error, isPending } = useEnginexQuery(() => q.wallet.getBalance(), { refetchInterval: 10_000 })
</script>

<template>
  <Skeleton v-if="isPending" />
  <ErrorMessage v-else-if="error" :code="error.code" />
  <p v-else-if="balance">{{ balance.realBalance }}</p>
</template>
```

### The getter rule

`useEnginexQuery` and `useEnginexMutation` receive a **getter** (`() => q.wallet.getBalance()`), never the
options already built. The reason: the key of user queries carries the `userId` **at the moment the factory is
called** (with no session, `'anonymous'`). The getter runs again when the session changes and when any ref read
inside it changes, and the key follows. A fixed object, built once in `setup`, would be stuck on the
`'anonymous'` key forever and never see the login:

```ts
// WRONG: the options are built once, with the user (or 'anonymous') at setup time
useEnginexQuery(q.wallet.getBalance()) // does not compile: the parameter is a getter

// RIGHT: the getter runs again when the session changes
useEnginexQuery(() => q.wallet.getBalance())
```

That is why the input that changes goes **inside** the getter, read from a `ref`:

```ts
const page = ref(1)
const { data, isPending } = useEnginexQuery(() => q.wallet.listTransactions({ page: page.value }))

page.value = 2 // the key changes and page 2 is fetched
```

### Return value and `overrides`

* **`useEnginexQueries()`** returns the core factories. Call the factory **inside the getter**, not outside.
* **Products:** `useEnginexQueries(createIgamingQueries, igaming)` (or `createPredictionsQueries`) returns the
  product package's factories.
* The return value is vue-query's `useQuery`, with `error` typed as `EnginexError`. As in vue-query,
  `data`, `error`, `isPending` etc. are refs (destructure and use them in the template, or read `.value` in the script).
  In TypeScript, `data` and `error` are unions of refs: the type is the form vue-query declares, and the template
  and `.value` work normally.
* **`overrides`** (second argument: `refetchInterval`, `select`, `enabled`, `staleTime`, `retry`...) win over
  the factory's options; `queryKey` and `queryFn` cannot be replaced. `undefined` values are ignored (they do not
  erase, for example, the `staleTime` of `config.*`).
* **`retry`:** accepts a number, boolean or function, or a ref of any of them. The **getter** form
  (`retry: () => 2`) is not supported, because it would be ambiguous with the function form
  `(failureCount, error) => boolean`; use a ref (`retry: ref(2)`) if the value needs to change.
* **Cancellation:** unmounting the last component that observes the query aborts the SDK's `fetch` and raises no
  error.
* **Default retry:** `UNAUTHENTICATED` (user query with no session) is not retried, because it made no request;
  the other errors follow the `QueryClient`'s `retry` (or `overrides.retry`).

### Product queries

```ts
import { createIgaming } from '@getenginex/sdk-igaming'
import { createIgamingQueries } from '@getenginex/sdk-igaming/query'

const igaming = createIgaming(enginex) // in the same module as the client, once

// in a component's setup
const ig = useEnginexQueries(createIgamingQueries, igaming)
const games = useEnginexQuery(() => ig.casino.listGames({ page: 1 }), { select: (page) => page.items })
```

## Mutations

```vue
<script setup lang="ts">
import { useEnginexMutation, useEnginexMutations } from '@getenginex/sdk-vue'

const m = useEnginexMutations()
const pix = useEnginexMutation(() => m.deposits.createPix(), {
  onSuccess: (deposit) => router.push(`/deposit/${deposit.id}`),
  onError: (error) => toast(error.code),
})
</script>

<template>
  <button :disabled="pix.isPending.value" @click="pix.mutate({ amount: 5000 })">Deposit</button>
</template>
```

* On success, it invalidates exactly `invalidates(input, result)` (here: balance, transactions and deposits),
  **waits for the refetches** and only then calls your `onSuccess`: `mutateAsync` and `isPending` finish with
  the data already updated.
* On error it invalidates nothing and `onError` receives the `EnginexError`. If your own `onSuccess` throws, the
  invalidation has already happened and `onError` receives its error (which is not necessarily an `EnginexError`).
* `useEnginexMutations(createIgamingMutations, igaming)` returns a product's mutations.
* As with queries, the first argument is a getter and `overrides` wins over the factory's options
  (`mutationFn` cannot be replaced).

### Idempotency in mutations {#idempotency-in-mutations}

Deposit, withdrawal (`request`, `confirmOtp`), `bonus.optIn/claim/redeemPromoCode`, `loyalty.redeem` and the
Predictions orders send an `Idempotency-Key`. The full rule (table of ambiguous failures, `ABORTED`,
explicit key) is in [Idempotency](/concepts/idempotency); in Vue:

* **The attempt lives in the composable instance.** `useEnginexMutation` keeps the attempt (input and
  key) per instance, and it survives the getter re-running and TanStack's `retry`. Two instances
  never share a key.
* **The method is part of the fingerprint.** The same instance that switches method (e.g. deposit ↔ withdrawal
  with the same input) does not reuse the other's key.
* **Adjustments go in the second argument.** Pass `retry`, `onSuccess` etc. in `overrides`. Spreading the options
  (`useEnginexMutation(() => ({ ...m.deposits.createPix(), retry: 1 }))`) loses the SDK's call, which the
  spread does not copy, and with it the per-instance attempt.
* **Only after an ambiguous failure.** `NETWORK_ERROR`, `TIMEOUT`, 5xx, `KEY_IN_USE` and `VALIDATION_ERROR` after
  a 2xx keep the key. Success, the other 4xx and `ABORTED` discard it: the next `mutate` is a new
  operation.
* **The input is compared by content.** A "try again" with a literal `pix.mutate({ amount: 5000 })`,
  after a 503, reuses the key. Changing the amount starts a new operation.
* **Explicit key:** `m.deposits.createPix({ idempotencyKey })` wins over the attempt, so you can store the key and
  repeat after reloading the page. Generate one per operation (when the player confirms), never one per
  screen. Since the getter runs again when the `ref` holding the key changes, a two-step flow works like this:

```ts
const operation = ref<{ amount: number; idempotencyKey: string }>()
const pix = useEnginexMutation(() => m.deposits.createPix({ idempotencyKey: operation.value?.idempotencyKey }))

// step 1: the player confirms the amount (one key per operation)
const confirm = (amount: number) => (operation.value = { amount, idempotencyKey: crypto.randomUUID() })
// step 2, on another click; "try again" calls pay() once more
const pay = () => operation.value && pix.mutate({ amount: operation.value.amount })
```

When in doubt, prefer the simple path: without an explicit key, the SDK takes care of it.

## Realtime

```vue
<script setup lang="ts">
import { coreTopics } from '@getenginex/sdk/realtime'
import { useRealtime, useRealtimeStatus, useRealtimeSync } from '@getenginex/sdk-vue'

useRealtimeSync() // balance and notifications in the cache, no polling
const status = useRealtimeStatus()

useRealtime(coreTopics.notification(), (n) => toast(n.title))
</script>

<template>
  <Banner v-if="status === 'reconnecting'">Reconnecting...</Banner>
</template>
```

* **`useRealtime(topic, handler)`** subscribes for as long as the scope (component or `effectScope`) exists and unsubscribes
  when it ends. `topic` accepts a value, ref or getter, and `null` does not subscribe (e.g. a market id not yet
  known). `handler` is a function or a ref of a function, and the latest one receives the messages without
  resubscribing. The topic is compared by key: an **equivalent** topic (`coreTopics.balance()` returned
  again by the getter) does not resubscribe, and a different topic does. A private topic is only subscribed with a
  user in the session and resubscribes on user switch.
* **`useRealtimeStatus()`** returns a read-only ref with
  `'connecting' | 'open' | 'reconnecting' | 'closed' | 'unavailable'`. It does not open the connection.
* **`useRealtimeSync(options?)`** is opt-in. With a user in the session, it invalidates the balance query on every
  `balance_update` (it never uses `setQueryData`: the message does not carry reserved and bonus amounts), the
  `notifications` queries on every notification and, after a reconnection (`onResync`), the `wallet` and
  `notifications` queries. Only active queries are refetched. `options` can be an object, a ref or a getter:
  with a ref or getter, the topics react to changes.

Product topics go in `topics`, each with the keys it feeds. Build the keys with the factories
(`.queryKey`), never by hand; use the function form for user keys, which depend on the session at the time
of the message. With a getter, the topic follows `marketId`:

```ts
import { createPredictions } from '@getenginex/sdk-predictions'
import { createPredictionsQueries } from '@getenginex/sdk-predictions/query'
import { predictionsTopics } from '@getenginex/sdk-predictions/realtime'

const predictions = createPredictions(enginex) // in the same module as the client, once

// in a component's setup
const props = defineProps<{ marketId: string }>()
const pq = useEnginexQueries(createPredictionsQueries, predictions)

useRealtimeSync(() => ({
  topics: [
    {
      topic: predictionsTopics.orderbook({ marketId: props.marketId }),
      invalidate: [pq.markets.getOrderbook({ marketId: props.marketId }).queryKey],
    },
    {
      topic: predictionsTopics.orders(),
      invalidate: () => [pq.orders.list().queryKey],
    },
  ],
}))
```

`useRealtimeSync` does not apply the messages' content to the cache: for that (e.g. applying orderbook
deltas), use `useRealtime`. The WebSocket URL and the rest of the connection follow the core's
[Realtime](/concepts/realtime) (`wsUrl` in `createEnginexClient`).

## Testing {#testing}

The core mocks (`createMockFetch` and `createMockRealtime`, from `@getenginex/sdk/testing`; see
[Testing and mocks](/guide/testing)) work with `@vue/test-utils`: mount the component in an app with
`EnginexPlugin` and a fake client.

```ts
import { createEnginexClient, memoryTokenStore } from '@getenginex/sdk'
import { createMockFetch, createMockRealtime } from '@getenginex/sdk/testing'
import { EnginexPlugin } from '@getenginex/sdk-vue'
import { flushPromises, mount } from '@vue/test-utils'
import { expect, it } from 'vitest'
import Balance from './Balance.vue'

it('shows the player balance', async () => {
  const realtime = createMockRealtime()
  const enginex = createEnginexClient({
    baseUrl: 'https://gateway.test',
    tenantHost: 'casino.test',
    tokenStore: memoryTokenStore(),
    fetch: createMockFetch(),
    webSocket: realtime.webSocket,
  })
  await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })

  const wrapper = mount(Balance, { global: { plugins: [[EnginexPlugin, { client: enginex }]] } })
  await flushPromises()

  expect(wrapper.text()).toContain('R$')
})
```

Each test mounts its own app, so the `QueryClient` (created by the plugin) is never shared between tests.
To control the cache, pass your own `queryClient` to the plugin. The
[`examples/vue-vite`](/guide/installation#examples)
project runs entirely in mock mode, with the balance updated by realtime.

## Nuxt: client-only {#nuxt-client-only}

The package has no SSR support. The factories build the key from the client's session, and on the server the
browser client has no session: a user query rendered during SSR would come out with the `'anonymous'` key and
break hydration. In Nuxt, use the SDK only on the client, with **both** measures below:

* install the plugin in a client-only Nuxt plugin (`plugins/enginex.client.ts`, below); and
* render the components that use the composables only on the client: wrap them in `<ClientOnly>` or name them
  `*.client.vue`.

One alone is not enough. With the client-only plugin, SSR still renders the components, and the first composable
throws because it cannot find `EnginexPlugin` in the server's app. With only `<ClientOnly>`, the plugin also runs on the
server, on every request, creating a client without the browser's session (there is no `localStorage` in Node) that
no component uses.

```ts
// plugins/enginex.client.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
import { EnginexPlugin } from '@getenginex/sdk-vue'

export default defineNuxtPlugin((nuxtApp) => {
  const enginex = createEnginexClient({ locale: 'pt-BR', tokenStore: localStorageTokenStore() })
  nuxtApp.vueApp.use(EnginexPlugin, { client: enginex })
})
```

**There is no server-side prefetch in Nuxt.** `sdk-vue` has no equivalent of `prefetchEnginex` (from
`@getenginex/sdk-next`) and does not hydrate queries: every query, including the public ones (configuration,
catalog), runs in the browser after the component mounts. Prefetching and hydrating queries on the server (SSR
via Nuxt) are outside this version.
