Migrando un player Next
Esta guía lleva un player Next que ya existe (como enginex-frontend-player, -igaming y -predictions) a @getenginex/sdk-next poco a poco: el SDK entra junto al código actual, y cada pantalla cambia de datos cuando esté lista. Nada tiene que cambiar de una sola vez.
El punto de partida son los players de hoy:
| Pieza | Hoy | Archivo |
|---|---|---|
| Next | ^16.3, App Router, src/proxy.ts | package.json |
| React y TanStack | React ^19.2, @tanstack/react-query ^5.101 | package.json |
| Tokens | zustand persist en localStorage (clave auth-storage); el servidor nunca ve el token | src/shared-modules/auth/ui/stores/useAuthStore.ts |
QueryClient | singleton en el navegador (staleTime 5 min, retry 1, sin refetch al enfocar); limpieza de las claves de usuario con una lista manual al cerrar sesión | src/app/(server-pages)/ClientProviders.tsx |
| SSR | anónimo y por tenant; prefetch con new QueryClient() → prefetchQuery → dehydrate → <HydrationBoundary> | src/app/(server-pages)/(igaming)/layout.tsx, src/subapps/igaming/ui/pages/lobby-prefetch.server.ts |
| Tenant en el servidor | host con fallback a x-forwarded-host | los mismos layouts |
| Gateway | NEXT_PUBLIC_API_URL; rewrites /api/:path* y /dev/:path* | next.config.ts |
x-original-host | proxy.ts escribe el header solo en /api y /dev | src/proxy.ts |
| Saldo | polling de 10 s en React Query y store alimentado por el WebSocket propio (wsService) | src/shared-modules/wallet/ui/hooks/useBalanceSync.ts, src/shared-modules/realtime/ |
1. Instala
pnpm add @getenginex/sdk @getenginex/sdk-next
pnpm add @getenginex/sdk-igaming # casino/sportsbook player
pnpm add @getenginex/sdk-predictions # predictions playerEl @tanstack/react-query, el react y el next del player ya sirven (peers ^5, >=19 y >=15).
2. Gateway: NEXT_PUBLIC_API_URL → ENGINEX_GATEWAY_URL
El cliente del servidor lee la URL del gateway de ENGINEX_GATEWAY_URL (solo del servidor, leída en cada request). Defínela con el mismo valor de NEXT_PUBLIC_API_URL en todos los ambientes (.env.local, el deploy, Amplify/Kubernetes):
NEXT_PUBLIC_API_URL=https://gateway.operador.com # stays: rewrites and the current code
ENGINEX_GATEWAY_URL=https://gateway.operador.com # new: getEnginexServerAlternativa sin variable nueva: getEnginexServer({ baseUrl: process.env.NEXT_PUBLIC_API_URL }). Recuerda que NEXT_PUBLIC_* se incrusta en el build; ENGINEX_GATEWAY_URL se lee en runtime.
baseUrl es solo el origen
El SDK acepta '' (mismo origen) o el origen del gateway (https://host[:puerto]) y agrega /api/v1 por su cuenta. Un valor con ruta (https://gateway.operador.com/api), barra final, query o credenciales lanza CONFIGURATION_ERROR al crear el cliente. Si el NEXT_PUBLIC_API_URL del player lleva /api, quítalo en el valor de ENGINEX_GATEWAY_URL.
3. Rewrites y proxy.ts: déjalos como están
El next.config.ts de los players ya reescribe /api y /dev hacia el gateway antes de los rewrites de locale (un orden que importa), y src/proxy.ts ya escribe x-original-host en esas rutas. Es todo lo que el cliente del navegador necesita: llama a /api/v1/... en el mismo origen.
withEnginexes opcional. Agrega el rewrite del gateway después de los de la app; como el player ya tiene/api/:path*y/dev/:path*sin condición, el helper no agregaría nada. Cámbialo solo si quieres quitar el rewrite manual, y comprueba el orden con los rewrites de locale.- Tenant en el servidor:
getEnginexServerusahost→x-forwarded-host, el mismo orden que usan hoy los layouts (headersList.get('host') || headersList.get('x-forwarded-host')). No necesitatrustOriginalHost.
Ingress que reescribe el Host
Si en algún ambiente el ingress reescribe el Host a un nombre interno (p. ej. el nombre del Service), getEnginexServer tomaría ese nombre como tenant. En ese caso, elige una de las dos opciones:
resolveHost, leyendo el header en el que el ingress guarda el dominio público (consulta Tenant); otrustOriginalHost: truecon unproxy.tsque sobrescribax-original-hosten todo request que renderiza, no solo en/apiy/dev:
// src/proxy.ts
import { NextResponse, type NextRequest } from 'next/server'
export function proxy(request: NextRequest) {
const headers = new Headers(request.headers)
// The public domain comes from the header where the ingress stores it, since `Host` arrives rewritten. Here,
// `x-forwarded-host`: swap in your ingress's header (check in production which one it is).
const host =
request.headers.get('x-forwarded-host')?.split(',')[0]?.trim() || request.headers.get('host')
// Always overwrite (or delete): the value the browser sent never reaches SSR or the gateway.
if (host) headers.set('x-original-host', host)
else headers.delete('x-original-host')
return NextResponse.next({ request: { headers } })
}
export const config = {
// Every request that renders (pages, /api, /dev), except Next's static files.
matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}Sin ese proxy.ts, no actives trustOriginalHost: en una página el x-original-host viene del navegador, y cualquiera elegiría el operador del SSR. El proxy.ts de hoy tiene un atajo que no clona los headers cuando el navegador ya envía x-original-host igual al host; eso sigue siendo correcto, pero el matcher actual (/api, /dev) no cubre las páginas.
4. Tokens: un TokenStore sobre zustand
El SDK no necesita otro lugar para la sesión: un TokenStore sobre useAuthStore hace que el SDK lea y escriba los mismos tokens que el resto del player, en el mismo auth-storage de localStorage.
// src/shared/lib/enginex.ts
import { createEnginexClient, type TokenStore } from '@getenginex/sdk'
import { createIgaming } from '@getenginex/sdk-igaming'
import { useAuthStore } from '@/shared-modules/auth/ui/stores/useAuthStore'
const authStoreTokens: TokenStore = {
get() {
const { accessToken, refreshToken } = useAuthStore.getState()
return accessToken && refreshToken ? { accessToken, refreshToken } : null
},
set({ accessToken, refreshToken }) {
useAuthStore.getState().updateTokens(accessToken, refreshToken)
useAuthStore.setState({ isAuthenticated: true })
},
clear() {
useAuthStore.getState().logout()
},
subscribe(listener) {
return useAuthStore.subscribe((state, prev) => {
if (state.accessToken !== prev.accessToken || state.refreshToken !== prev.refreshToken) listener()
})
},
}
export const enginex = createEnginexClient({ locale: 'pt-BR', tokenStore: authStoreTokens })
export const igaming = createIgaming(enginex)- El inicio y el cierre de sesión del player siguen funcionando: el
setAuth/logoutdel store cambian los tokens ysubscribeavisa al SDK. En la fase A (abajo) el inicio y el cierre de sesión son solo del player; en la fase B, un inicio de sesión hecho por el SDK (enginex.auth.login) escribe los tokens conset, y eluserdel store sigue siendo del player. - En el servidor este módulo no tiene tokens (
persistno encuentralocalStorage), así que importarlo en un Client Component renderizado en el SSR es seguro. Para datos en el servidor, usa siempregetEnginexServer. - Exactamente un dueño del refresh: consulta la sección de abajo antes de activar el cliente en producción.
- La cookie es opcional: la sesión puede seguir en
localStorage. Pasar anextCookieTokenStoresolo tiene sentido para SSR con datos del jugador, y trae los costos de la tabla de comparación (HTTPS obligatorio fuera delocalhost, refresh token en los logs, cuidado con el caché y el HTML).
Un solo dueño del refresh
Con los dos clientes leyendo el mismo store, ambos saben renovar la sesión: el SDK renueva antes de que venza el access token (faltando 2 minutos) y después de un 401; el cliente HTTP del player (http-client.api.browser.ts) renueva después de un 401. El SDK suele llegar primero, pero nada lo garantiza (pestañas en segundo plano, reloj, un 401 de los dos al mismo tiempo). Si los dos cambian el mismo refresh token, el segundo refresh puede ser rechazado y la sesión se cae. Por eso la migración tiene un dueño del refresh a la vez:
Fase A, convivencia: el player renueva, el SDK no. El cliente del SDK arranca con sessionOwner: 'app': usa el access token que está en el store, nunca llama a /auth/refresh y no escribe ni limpia tokens (auth.login y auth.logout lanzan CONFIGURATION_ERROR antes de enviar). El cliente actual sigue siendo dueño del refresh y escribe los tokens nuevos en useAuthStore, y el subscribe del TokenStore avisa al SDK. Cuando el gateway rechaza el token (401), el SDK llama a onAccessTokenRejected una vez por token, incluso en una ráfaga de queries; es el lugar para pedir el refresh a su dueño. Consulta Sesión y tokens.
// src/shared/lib/enginex.ts (fase A)
export const enginex = createEnginexClient({
locale: 'pt-BR',
tokenStore: authStoreTokens,
sessionOwner: 'app', // the player's HTTP client is the only one that refreshes
// An SDK 401 (expired token) asks its owner for the refresh, which already avoids duplicate refreshes.
onAccessTokenRejected: () => {
if (useAuthStore.getState().refreshToken) void refreshPlayerSession() // e.g. the current client's refreshOnce/sessionProvider.refreshToken()
},
})El costo: una llamada del SDK hecha entre el vencimiento del access token y el próximo refresh del player falla con UNAUTHENTICATED (el 401 del gateway, sin refresh ni nuevo intento). useEnginexQuery no reintenta ese error. Rehaz las queries con error cuando el token cambie:
// in a component inside the EnginexProvider (e.g. ClientProviders)
import { enginexKeys } from '@getenginex/sdk/query'
import { useQueryClient } from '@tanstack/react-query'
import { useEffect } from 'react'
const queryClient = useQueryClient()
useEffect(
() =>
useAuthStore.subscribe((state, prev) => {
if (state.accessToken && state.accessToken !== prev.accessToken) {
void queryClient.refetchQueries({
queryKey: enginexKeys.user(),
predicate: (query) => query.state.status === 'error',
})
}
}),
[queryClient],
)Una mutation que falló así no se reintenta sola: muestra el error con "reintentar", o, en un mutateAsync, espera el refresh del player y vuelve a llamar una vez. Un 401 libera la clave de idempotencia (no es una falla ambigua): la nueva llamada es una operación nueva, y no duplica nada porque el gateway rechazó la primera antes de procesarla.
Fase B, el SDK es el dueño. Cuando el inicio de sesión y las llamadas autenticadas ya pasan por el SDK, invierte: cambia a sessionOwner: 'sdk' (el valor por defecto; quita el sessionOwner y el onAccessTokenRejected de arriba, que juntos solo valen en la fase A), y elimina el refresh del interceptor antiguo (lo que quede del cliente HTTP del player solo lee el token del store; un 401 en él se convierte en un error o llama a una query del SDK). A partir de ahí el SDK renueva antes de vencer y después de un 401, y escribe en el store con set.
Nunca dejes a los dos renovando al mismo tiempo, ni siquiera por un deploy.
5. Provider con el QueryClient existente
En ClientProviders.tsx, envuelve el árbol con EnginexProvider pasando el mismo QueryClient:
// src/app/(server-pages)/ClientProviders.tsx (excerpt)
'use client'
import { EnginexProvider } from '@getenginex/sdk-next'
import { QueryClientProvider } from '@tanstack/react-query'
import { enginex } from '@/shared/lib/enginex'
export default function ClientProviders({ children }: ClientProvidersProps) {
const queryClient = getQueryClient() // the same one as today: staleTime 5 min, retry 1
return (
<EnginexProvider client={enginex} queryClient={queryClient}>
{/* the current QueryClientProvider can go: the EnginexProvider already renders it with the same client */}
{children}
</EnginexProvider>
)
}- El
QueryClientdel player se usa tal como viene: elstaleTimede 5 minutos sigue valiendo para las queries del SDK y evita un nuevo request después de la hidratación. ElstaleTimede 60 s del SDK solo vale cuando la app no pasa el suyo. - Al cambiar de usuario el provider elimina
['enginex', 'user']. Las claves antiguas del player (['wallet'],['campaignOffers']...) siguen en la lista declearUserScopedQuerieshasta que migre la última pantalla que las usa.
6. Cambia las queries una pantalla a la vez
Las claves del SDK (['enginex', 'user', userId, 'wallet', 'getBalance']) son distintas de las del player (['balance']). Migra los lectores y escritores de un mismo dato juntos: si el saldo viene del SDK pero el depósito todavía invalida ['balance'], el saldo nuevo no se actualiza después del depósito.
Ejemplo, el saldo (useBalanceSync.ts):
'use client'
import { useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-next'
export function useBalance() {
const q = useEnginexQueries()
return useEnginexQuery(q.wallet.getBalance(), { refetchInterval: 10_000 })
}Y el depósito, que invalida saldo, transacciones y depósitos solo:
import { useEnginexMutation, useEnginexMutations } from '@getenginex/sdk-next'
const m = useEnginexMutations()
const pix = useEnginexMutation(m.deposits.createPix())Quita la idempotencia manual. Los crypto.randomUUID() y los Maps de claves que el player guarda para depósito, retiro y bono salen junto con ella: con useEnginexMutation, la Idempotency-Key solo se reutiliza después de una falla ambigua (red, timeout, 5xx, KEY_IN_USE o VALIDATION_ERROR después de un 2xx), para la misma entrada, y queda guardada por instancia del hook. Un "reintentar" con un pix.mutate({ amount }) literal ya reutiliza la clave. Mantén una clave propia (m.deposits.createPix({ idempotencyKey })) solo donde la operación necesite sobrevivir a una recarga. Consulta React.
Claves del usuario. Para invalidar los datos del SDK desde dentro de un componente, useUserKey('wallet') (de @getenginex/sdk-next) devuelve el prefijo del jugador con sesión iniciada, o null sin sesión; fuera de un componente, enginexKeys.user(userId, 'wallet').
Un orden que funciona bien: configuración y catálogo (públicos, sin riesgo), después saldo y billetera (lectura y depósito/retiro juntos), después el resto. Los hooks del player que ya llaman al gateway siguen funcionando mientras tanto.
7. Prefetch en el servidor
El prefetchCatalog de hoy crea un QueryClient, llama a prefetchQuery con las claves propias y devuelve el dehydrate. Con el SDK:
// src/app/(server-pages)/(igaming)/layout.tsx (excerpt)
import { HydrationBoundary } from '@tanstack/react-query'
import { createIgaming } from '@getenginex/sdk-igaming'
import { createIgamingQueries } from '@getenginex/sdk-igaming/query'
import { getEnginexServer, prefetchEnginex } from '@getenginex/sdk-next/server'
const enginex = await getEnginexServer({ next: { revalidate: 300, tags: ['catalog'] } })
const catalog = await prefetchEnginex(createIgamingQueries(createIgaming(enginex)), (ig) => [
ig.casino.listCategories(),
ig.casino.listProviders(),
])
return (
<HydrationBoundary state={catalog}>
<IGamingLayout>{children}</IGamingLayout>
</HydrationBoundary>
)- El tenant sale de
headers()dentro degetEnginexServer; el layout ya no necesita leer elhost. - Cambia el componente junto con esto: el rail necesita leer con
useEnginexQuery(ig.casino.listCategories()), o el dato hidratado (con la clave del SDK) queda sin uso y el componente pide el suyo. - Las tags son fijas por llamada. Hoy el player usa una tag por host (
catalog-${host}) para invalidar un solo tenant; para mantenerlo, lee el host tú mismo y pásalo entags. La respuesta ya está separada por tenant en la clave del Data Cache (elX-Original-Hostdel request entra en ella). - El prefetch sigue siendo anónimo: nada de datos del jugador en el SSR, como hoy.
- No incluyas
sdk-nextenserverExternalPackages: fuera del bundle del servidor, el import deserver-onlydel entry/serverfalla ynext buildse detiene con el error deserver-only. Si el player ya tiene esa lista, comprueba que el SDK no esté en ella.
8. Realtime: apaga el WebSocket propio antes de useRealtimeSync
useRealtimeSync() abre la conexión del SDK e invalida saldo y notificaciones en cada mensaje. Con el wsService del player todavía activo para los mismos eventos, quedan dos conexiones y cada balance_update se procesa dos veces (store de zustand y caché). Por tópico:
- quita de
wsService(useRealTimeUpdates) la suscripción de saldo y de notificaciones del usuario; - activa
useRealtimeSync()una vez, en el shell de la app; - lee el saldo de la query (
useBalancede arriba), no del store alimentado por el WebSocket; - con el realtime estable, el
refetchIntervalde 10 s puede subir o eliminarse.
La URL del WebSocket viene de wsUrl en createEnginexClient (sin ella, del origen de la página + /ws, por el mismo proxy). Los tópicos de predictions (orderbook, órdenes) entran en useRealtimeSync({ topics }) o useRealtime, consulta React.
Checklist
- [ ]
ENGINEX_GATEWAY_URLdefinida en todos los ambientes, con el valor deNEXT_PUBLIC_API_URL. - [ ] Tenant del SSR comprobado en cada ambiente (¿el
Hostllega con el dominio público?). - [ ]
trustOriginalHostsolo con elproxy.tsque cubre todo request que renderiza. - [ ]
EnginexProvidercon elQueryClientdel player (staleTime5 min). - [ ] Cada dato migrado con lectores y escritores juntos; claves antiguas todavía en
clearUserScopedQueries. - [ ] Componentes hidratados leyendo con las fábricas del SDK (misma clave del prefetch).
- [ ]
wsServicesin saldo ni notificaciones antes deuseRealtimeSync. - [ ] Nada de
tokenStoreconnext.revalidate, ni datos del jugador en el prefetch. - [ ] Exactamente un dueño del refresh: fase A con
sessionOwner: 'app'yonAccessTokenRejecteden el SDK; fase B consessionOwner: 'sdk'y el refresh del interceptor antiguo eliminado. - [ ]
baseUrl/ENGINEX_GATEWAY_URLsolo con el origen (sin/api). - [ ] Idempotencia manual eliminada donde
useEnginexMutationya se encarga de ella.