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

The core (`@getenginex/sdk`) is plain TypeScript and runs anywhere. For apps with
[TanStack Query](https://tanstack.com/query) v5, the SDK ships these layers (React, Vue and Next.js are adapters on top of the queries layer):

| Layer | Package | What it provides |
| --- | --- | --- |
| Queries | `@getenginex/sdk/query`, `@getenginex/sdk-igaming/query`, `@getenginex/sdk-predictions/query` | `{ queryKey, queryFn }` factories and `{ mutationKey, mutationFn, invalidates }` mutations for any framework, with no TanStack dependency |
| React | `@getenginex/sdk-react` | `EnginexProvider`, `useSession`, `useEnginexQuery`, `useEnginexMutation`, `useRealtime` and `useRealtimeSync` |
| Vue | `@getenginex/sdk-vue` | `EnginexPlugin`, `useSession`, `useEnginexQuery`, `useEnginexMutation`, `useRealtime` and `useRealtimeSync`, on top of `@tanstack/vue-query` |
| Next.js | `@getenginex/sdk-next` | everything in `sdk-react` and, in the App Router, the per-request client (`getEnginexServer`), prefetching (`prefetchEnginex`), the session cookie (optional) and the gateway rewrite (`withEnginex`) |

| Your app is | Use | Page |
| --- | --- | --- |
| React (Vite, CRA, React Native with TanStack) | `@getenginex/sdk-react` | [React](/frameworks/react) |
| Next.js with the App Router | `@getenginex/sdk-next` (installs `sdk-react` with it) | [Next.js](/frameworks/next) |
| an existing Next player | `@getenginex/sdk-next`, gradually | [Migrating a Next player](/frameworks/migrating-next-player) |
| Vue 3 (Vite, Nuxt client-only) | `@getenginex/sdk-vue` | [Vue](/frameworks/vue) |
| Svelte, Solid, Angular or TanStack without React | the `/query` factories | [No adapter](/frameworks/no-adapter) |

## Versions

| Package | Peers |
| --- | --- |
| `@getenginex/sdk-react` | `@getenginex/sdk >=0.6.0 <1.0.0`, `react >=18`, `@tanstack/react-query ^5` |
| `@getenginex/sdk-vue` | `@getenginex/sdk >=0.6.0 <1.0.0`, `vue >=3.5`, `@tanstack/vue-query ^5` |
| `@getenginex/sdk-next` | `@getenginex/sdk >=0.6.0 <1.0.0`, `next >=15`, `react >=19`, `@tanstack/react-query ^5` |

`sdk-next` depends on `sdk-react` (the app does not install both) and the two always ship with the same
version. The `/query` entries of the product packages require core `>=0.6.0`.

## The queries layer {#queries-layer}

Every read method in the namespaces has a query factory with the same name and the same input; every
write method has a mutation:

```ts
import { createMutations, createQueries } from '@getenginex/sdk/query'
import { createIgamingQueries } from '@getenginex/sdk-igaming/query'

const q = createQueries(enginex)
q.wallet.getBalance()               // { queryKey, queryFn }
q.wallet.listTransactions({ page }) // same input as enginex.wallet.listTransactions
q.config.get()                      // { queryKey, queryFn, staleTime: 300_000 }

const m = createMutations(enginex)
m.deposits.createPix()              // { mutationKey, mutationFn, invalidates }

const ig = createIgamingQueries(igaming)
ig.casino.listGames({ page: 1 })
```

The returned object works as-is with TanStack's `useQuery`, `prefetchQuery`, `fetchQuery` and `useMutation`
(React, Vue, Svelte, Solid). The SDK does not depend on TanStack: the factories are plain objects.

### Keys

| Data | Key |
| --- | --- |
| no session (configuration, casino catalog, public offers, markets) | `['enginex', 'public', namespace, method, input?]` |
| player-specific (balance, profile, transactions, orders...) | `['enginex', 'user', userId, namespace, method, input?]` |

* The `userId` is the session's **at the moment the factory is called**. With no session, the key uses
  `'anonymous'` and the `queryFn` rejects with `UNAUTHENTICATED` without making a request; the same happens if
  the session switches user before the `fetch`. That is why you call the factory again after a login
  (`sdk-react` and `sdk-vue` do this on their own).
* The `input` is only included when provided. No key carries a token, password or personal data other than the `userId`.
* The `'enginex'` prefix coexists with the app's own keys (`['balance']` stays the app's).
* `enginexKeys` provides the prefixes to invalidate or remove groups: `enginexKeys.all`, `enginexKeys.public`,
  `enginexKeys.user()` (all users) and `enginexKeys.user(userId)`.

### Cancellation and `staleTime`

The `queryFn` passes TanStack's `signal` to the SDK's `fetch`: a canceled query (unmounted component,
`cancelQueries`) aborts the request. Only the `config.*` factories carry a `staleTime` (5 minutes); the
others follow the app's `QueryClient`.

### Mutations and invalidation

`invalidates(input, result)` lists the key prefixes that the write leaves stale. Call it **only after
success** (`sdk-react` and `sdk-vue` do this in `useEnginexMutation`):

| Mutation | Invalidates |
| --- | --- |
| `deposits.createPix`, `withdrawals.request/confirmOtp/cancel` | `wallet` (balance and transactions) and the namespace list |
| `pixKeys.add/remove/setDefault` | `pixKeys.list` |
| `notifications.markAsRead/updatePreferences` | `notifications` |
| `profile.update`, `auth.verifyEmail/verifyPhone/confirmPhoneChange` | `profile.get` |
| `auth.login`, `auth.logout` | `['enginex', 'user']` (all users) |
| `bonus.optIn/claim/redeemPromoCode`, `loyalty.redeem` (iGaming) | the namespace and `wallet` |
| `orders.place/placeBatch/cancel/amend` (Predictions) | `orders`, `portfolio` and `wallet` |

The full list is in the reference for [`createMutations`](/reference/api/@getenginex/sdk/query/functions/createMutations),
[`createIgamingMutations`](/reference/api/@getenginex/sdk-igaming/query/functions/createIgamingMutations) and
[`createPredictionsMutations`](/reference/api/@getenginex/sdk-predictions/query/functions/createPredictionsMutations).

* **`mutationKey`** is `['enginex', namespace, method]`, without the input (which may contain a password).
* **`gcTime: 0`** on mutations that carry credentials or personal data (`auth.*`, except `logout`, and
  `withdrawals.confirmOtp`; in iGaming, promo code, launching a game and the sportsbook session): input and
  result leave the `MutationCache` (and the devtools) as soon as no component observes the mutation.
  While the component with the `useMutation` is mounted, `variables` (the password, on login) and the result
  stay; call `reset()` when you no longer need them (e.g. in the login's `onError`, keeping the error to
  display in state).
* **Idempotency:** deposit, withdrawal, redemptions and orders send an `Idempotency-Key`, kept per hook
  instance (or per options object, outside React) and compared by the input's content. It is only
  reused after an ambiguous failure (network, timeout, 5xx, `KEY_IN_USE` or `VALIDATION_ERROR` after a 2xx), so TanStack's `retry` does not duplicate a
  deposit, and it is discarded on success and on any other error. See [Idempotency](/concepts/idempotency) and the section
  [Idempotency in mutations](/frameworks/react#idempotency-in-mutations).

### Factory types

`@getenginex/sdk/query` exports the types of what the factories return, to type the app's own helpers
without repeating the SDK's shapes:

| Type | What it describes |
| --- | --- |
| `EnginexQueryOptions<T>` | what a query factory returns: `{ queryKey, queryFn, staleTime? }`, with `T` the method's result |
| `EnginexMutationOptions<I, R>` | what a mutation factory returns: `{ mutationKey, mutationFn, invalidates, gcTime? }` |
| `EnginexQueryKey` | the key tuple (`['enginex', 'public', ...]` or `['enginex', 'user', userId, ...]`) |
| `EnginexQueryFnContext` | the context `queryFn` receives (only `signal` is used) |
| `QueryFactory<F>`, `MutationFactory<F>`, `IdempotentMutationFactory<F>` | the factory of one method `F` |
| `QueriesOf<Api, K>`, `MutationsOf<Api, K>`, `IdempotentMutationsOf<Api, K>` | the factories of the methods `K` of a namespace `Api` |
| `EnginexMutationFactoryOptions` | `{ idempotencyKey? }`, accepted by the idempotent mutation factories |
| `CoreQueries`, `CoreMutations` | what `createQueries` and `createMutations` return |

The product packages export theirs from their own `/query` entry: `IgamingQueries`, `IgamingMutations`,
`PredictionsQueries` and `PredictionsMutations`.

```ts
import type { Page } from '@getenginex/sdk'
import type { EnginexQueryOptions, QueriesOf } from '@getenginex/sdk/query'
import type { CasinoApi, Game } from '@getenginex/sdk-igaming'
import type { IgamingQueries } from '@getenginex/sdk-igaming/query'

// Any SDK query goes through the same helper: the type carries the method's result.
function withAppDefaults<T>(options: EnginexQueryOptions<T>): EnginexQueryOptions<T> {
  return { ...options, staleTime: options.staleTime ?? 30_000 }
}

const lobby: EnginexQueryOptions<Page<Game>> = withAppDefaults(ig.casino.listGames({ page: 1 }))

// The factories of a namespace, read from the product type or built from its API.
type CasinoQueries = IgamingQueries['casino']
type CatalogQueries = QueriesOf<CasinoApi, 'listGames' | 'getGame'>
```

## Building factories: `queryScope` {#query-scope}

`queryScope(source)` gives the pieces `createQueries`, `createIgamingQueries` and
`createPredictionsQueries` are made of. It is meant for **SDK packages and adapters**: an app uses the
ready-made factories. `source` is the core client or the object of a product package registered with
`registerProductClient` (from `@getenginex/sdk/extension`); anything else, including a `{ ...igaming }`
copy, throws `CONFIGURATION_ERROR`.

```ts
import type { CallOptions } from '@getenginex/sdk'
import { queryScope } from '@getenginex/sdk/query'
import type { IgamingClient, ListGamesInput, RedeemPointsInput } from '@getenginex/sdk-igaming'

export function createLobbyFactories(igaming: IgamingClient) {
  const scope = queryScope(igaming) // the core client or a product client registered with registerProductClient
  return {
    // ['enginex', 'public', 'casino', 'listGames', input]
    games: (input: ListGamesInput) =>
      scope.publicQuery('casino', 'listGames', (i, o) => igaming.casino.listGames(i, o), input),
    // ['enginex', 'user', userId, 'loyalty', 'get']: rejects with UNAUTHENTICATED without a session
    points: () =>
      scope.userQuery('loyalty', 'get', (_i: undefined, o: CallOptions) => igaming.loyalty.get(undefined, o), undefined),
    // ['enginex', 'loyalty', 'redeem'], with the attempt's Idempotency-Key
    redeem: () =>
      scope.mutation(
        'loyalty',
        'redeem',
        (i: RedeemPointsInput, o) => igaming.loyalty.redeem(i, o),
        () => [scope.userPrefix('loyalty'), scope.userPrefix('wallet')],
        { idempotent: true },
      ),
  }
}
```

| Piece | What it does |
| --- | --- |
| `publicQuery(namespace, method, call, input, defaults?)` | factory with a `public` key; `defaults.staleTime` is optional |
| `userQuery(namespace, method, call, input)` | factory with the key of the session's user at call time; the `queryFn` rejects with `UNAUTHENTICATED`, without a request, when the session is missing or belongs to another user |
| `mutation(namespace, method, call, invalidates, options?)` | `{ mutationKey, mutationFn, invalidates }`; with `idempotent: true`, the `Idempotency-Key` follows the attempt rule; `gcTime` and a fixed `idempotencyKey` are optional |
| `publicKey`, `userKey`, `userPrefix` | the keys and prefixes, to build `invalidates` (e.g. `scope.userPrefix('wallet')` for the balance) |
| `userId()` | the session's `userId` right now, or `undefined` |

`call` receives the input and the `CallOptions` (with the query's `signal`): pass them on to the method so that
cancellation reaches the `fetch`. The adapters (`sdk-react`, `sdk-vue`) read the mutation's call to keep the
attempt per hook instance; see [Extensibility](/concepts/extensibility#custom-mutation).
