Next.js
@getenginex/sdk-next es el adapter del App Router. Tiene tres entries:
| Entry | Dónde corre | Qué incluye |
|---|---|---|
@getenginex/sdk-next | Client Components | todo lo de @getenginex/sdk-react y nextCookieTokenStore (sesión en cookie, opcional) |
@getenginex/sdk-next/server | Server Components, Server Actions, Route Handlers (server-only) | getEnginexServer, prefetchEnginex y readCookieTokenStore |
@getenginex/sdk-next/config | next.config.ts | withEnginex, el rewrite /api/:path* → gateway |
npm i @getenginex/sdk @getenginex/sdk-next @tanstack/react-queryPeers: next >=15, react >=19, @tanstack/react-query ^5 y @getenginex/sdk >=0.6.0 <1.0.0. sdk-react viene como dependencia (misma versión que sdk-next). Importar @getenginex/sdk-next/server en un Client Component rompe el build (server-only).
El modelo es el de los players: SSR anónimo y por tenant (configuración, catálogo, CMS), sesión en el navegador (localStorage) y el navegador llamando al gateway por el mismo origen (/api, vía rewrite).
Cliente
El provider es el mismo de React. Crea el cliente del navegador en un módulo 'use client':
// app/providers.tsx
'use client'
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
import { EnginexProvider } from '@getenginex/sdk-next'
const enginex = createEnginexClient({ locale: 'pt-BR', tokenStore: localStorageTokenStore() })
export function Providers({ children }: { children: React.ReactNode }) {
return <EnginexProvider client={enginex}>{children}</EnginexProvider>
}// app/layout.tsx
import { Providers } from './providers'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="pt-BR">
<body>
<Providers>{children}</Providers>
</body>
</html>
)
}En el navegador el SDK llama a /api/v1/... en el mismo origen y envía el dominio de la página como tenant; el rewrite (abajo) lleva el request al gateway.
Servidor: getEnginexServer
// app/page.tsx (Server Component)
import { getEnginexServer } from '@getenginex/sdk-next/server'
export default async function Page() {
const enginex = await getEnginexServer({ next: { revalidate: 300, tags: ['config'] } })
const config = await enginex.config.get()
return <p>Currency: {config.defaultCurrency}</p>
}# server .env (no NEXT_PUBLIC_)
ENGINEX_GATEWAY_URL=https://gateway.operador.com- Gateway: el
baseUrlde la opción o la variableENGINEX_GATEWAY_URL, leída en cada request (URL absoluta). Sin ninguna de las dos, la promise rechaza conCONFIGURATION_ERRORantes de cualquierfetch. Si la app ya tiene la URL enNEXT_PUBLIC_API_URL, defineENGINEX_GATEWAY_URLcon el mismo valor (o pasabaseUrl: process.env.NEXT_PUBLIC_API_URL). - Un cliente por request, memoizado con el
cache()de React: en el mismo request, opciones iguales devuelven el mismo cliente (tagscomparadas por contenido,resolveHostytokenStorepor referencia, así que defínelos fuera del componente). Requests distintos nunca comparten cliente, y no hay cliente en el ámbito del módulo. Fuera de un render de React (Route Handler), cada llamada crea un cliente nuevo. - No pongas
sdk-nextenserverExternalPackages: fuera del bundle del servidor, el import deserver-onlydel entry/serverfalla ynext buildse detiene con el error deserver-only(verificado con Turbopack y webpack). Deja que Next empaquetesdk-next. - Anónimo por defecto: no lee cookies, usa un
memoryTokenStore()vacío yautoRefresh: false. Las queries de usuario hechas con él rechazan conUNAUTHENTICATEDsin request. - Caché de Next:
next: { revalidate, tags }va en todofetchdel cliente; unfetchOptions.nexten una llamada prevalece campo a campo. La clave del Data Cache incluye los headers del request, así que tenants (X-Original-Hostenviado al gateway) y tokens (Authorization) distintos nunca comparten respuesta. - Leer
headers()vuelve dinámica la ruta, como cualquier dato por tenant.
Tenant
El dominio del operador sale de headers(), en este orden:
host: el dominio que pidió el navegador;x-forwarded-host: último recurso.
Es lo que los players ya hacen en el SSR. De una lista (a.com, proxy.interno), vale el primer valor; el puerto queda como vino (el gateway lo quita). Sin ninguno de los dos, rechaza con CONFIGURATION_ERROR.
| Opción | Efecto |
|---|---|
trustOriginalHost: true | x-original-host pasa a venir antes de host. Solo con un proxy.ts que lo sobrescriba en todo request que renderiza (abajo). |
resolveHost(headers) | reemplaza el descubrimiento por completo (ignora el orden y trustOriginalHost); devolver undefined rechaza con CONFIGURATION_ERROR. |
x-original-host viene del navegador
En un request de página, x-original-host llega tal como lo envió el navegador: el proxy.ts de los players solo lo sobrescribe en /api y /dev. Confiar en él sin un proxy.ts que lo escriba en todo request dejaría que cualquiera elija el operador del SSR: la página de un dominio se renderizaría con la configuración, el catálogo y el CMS de otro operador (y, con next.revalidate, guardaría esas respuestas en el Data Cache).
proxy.ts con x-original-host
El gateway encuentra al operador por el X-Original-Host. Los requests del navegador pasan por el rewrite /api, y el proxy.ts de la app (el middleware.ts antes de Next 16) escribe el header con el host de la página. Para activar también trustOriginalHost, el proxy.ts debe sobrescribir el header en todo request que renderiza, no solo en /api:
// src/proxy.ts
import { NextResponse, type NextRequest } from 'next/server'
export function proxy(request: NextRequest) {
const headers = new Headers(request.headers)
const host = 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).*)'],
}const enginex = await getEnginexServer({ trustOriginalHost: true })Si un ingress reescribe el Host a un nombre interno (p. ej. player.default.svc.cluster.local), el orden por defecto toma ese nombre. En ese caso usa resolveHost con el header en el que el ingress guarda el dominio público, o escribe ese header como x-original-host en el proxy.ts de arriba (en lugar de host) y activa trustOriginalHost:
// outside the component, so the client is reused within the same request
const publicHost = (headers: Headers) => headers.get('x-forwarded-host')?.split(',')[0]?.trim()
const enginex = await getEnginexServer({ resolveHost: publicHost })Comprueba en producción qué header trae el dominio público antes de elegir: depende del ingress.
Prefetch: prefetchEnginex
// app/layout.tsx (Server Component)
import { HydrationBoundary } from '@tanstack/react-query'
import { getEnginexServer, prefetchEnginex } from '@getenginex/sdk-next/server'
import { Providers } from './providers'
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const enginex = await getEnginexServer({ next: { revalidate: 300 } })
const state = await prefetchEnginex(enginex, (q) => [q.config.get(), q.config.getProducts()])
return (
<html lang="pt-BR">
<body>
<Providers>
<HydrationBoundary state={state}>{children}</HydrationBoundary>
</Providers>
</body>
</html>
)
}selectrecibe las fábricas del core (con el cliente del servidor) o las de un paquete de producto. Las claves son las mismas que usauseEnginexQueryen el navegador, así que el componente encuentra el dato hidratado:tsimport { createIgaming } from '@getenginex/sdk-igaming' import { createIgamingQueries } from '@getenginex/sdk-igaming/query' const igaming = createIgaming(await getEnginexServer({ next: { revalidate: 300, tags: ['catalog'] } })) const state = await prefetchEnginex(createIgamingQueries(igaming), (ig) => [ ig.casino.listCategories(), ig.casino.listProviders(), ])Un
QueryClientnuevo por llamada, sin retry, descartado al final (nada queda entre requests).Una fábrica que falla no tumba a las otras y queda fuera del estado: solo las queries con éxito se deshidratan, nunca un error. El navegador pide las que faltaron. Con el cliente anónimo, las queries de usuario quedan fuera (sin request).
staleTime: el estado deshidratado lleva solo la clave y el dato. Quien decide si el navegador vuelve a pedir apenas se monta es elstaleTimedelQueryClientdel navegador: el que creaEnginexProviderusa 60 s; en el tuyo, usa uno mayor que cero (los players usan 5 min). Con el valor por defecto de TanStack (0), el navegador rehace todo justo después de hidratar (menosconfig.*, que tienestaleTimepropio).
Sesión en cookie (opcional)
Lo habitual sigue siendo la sesión en localStorage y el SSR anónimo. Con la sesión en cookie, el servidor también la lee, para páginas con datos del jugador renderizadas en el servidor:
// app/providers.tsx
'use client'
import { createEnginexClient } from '@getenginex/sdk'
import { nextCookieTokenStore } from '@getenginex/sdk-next'
const enginex = createEnginexClient({ tokenStore: nextCookieTokenStore({ maxAge: 60 * 60 * 24 * 30 }) })// app/account/page.tsx (Server Component)
import { getEnginexServer, readCookieTokenStore } from '@getenginex/sdk-next/server'
export default async function Account() {
const enginex = await getEnginexServer({ tokenStore: await readCookieTokenStore() })
const balance = await enginex.wallet.getBalance()
return <p>Balance: {balance.realBalance}</p>
}- Cookie:
getenginex.tokens=<tokens>; Path=/; SameSite=Lax; Secure, sinDomain.name,maxAge(segundos; sin él, cookie de sesión del navegador) ypathson opciones; usa el mismonameenreadCookieTokenStore({ name }). Los valores inválidos lanzanCONFIGURATION_ERRORen la creación. - Sin
HttpOnly, a propósito: el refresh de la sesión y el?token=del WebSocket necesitan el token en JavaScript. - El servidor solo lee: los Server Components no escriben cookies. Quien renueva y reescribe la sesión es el navegador; un access token vencido hace que las llamadas del servidor fallen con
UNAUTHENTICATEDhasta entonces. initialSession: solo para la parte de la pantalla que depende solo de la sesión (encabezado con el botón de cerrar sesión, menú del jugador): pasa alEnginexProviderla sesión leída en el servidor (enginex.session.get()del cliente con elreadCookieTokenStore()), en un Client Component que la reciba por prop, y el servidor y la hidratación renderizan la misma sesión. No envuelvas con uninitialSessionautenticado componentes que renderizan queries de usuario del SDK en el SSR (ver abajo).- Fuera del navegador (el SSR de un Client Component),
nextCookieTokenStoreno guarda nada.
Datos del jugador: Server Component o después de la hidratación
Las fábricas arman la clave de una query de usuario con la sesión del cliente del navegador (client.session), no con initialSession. En el SSR de un Client Component ese cliente no tiene sesión (nextCookieTokenStore no lee nada sin document), así que q.wallet.getBalance() renderizado en el servidor usa la clave 'anonymous': el HTML sale sin el dato del prefetch y la hidratación falla (el navegador renderiza la clave del jugador, con el dato). Por eso:
En Client Components, renderiza las queries de usuario solo después de la hidratación: condiciona el componente al
useSession()autenticado, con elinitialSessionpor defecto (anónimo), como elAccountdel ejemplo. El servidor y la hidratación renderizan la rama anónima; enseguida aparece la sesión real y el componente se monta. SiprefetchEnginextrajo el dato del jugador (conreadCookieTokenStore()), ese primer render del cliente ya lo usa, sin request.tsx'use client' function Account() { const session = useSession() return session.status === 'authenticated' ? <Wallet /> : <LoginForm /> }En el HTML del servidor, renderiza los datos del jugador en un Server Component (
getEnginexServer({ tokenStore: await readCookieTokenStore() }), comoapp/account/page.tsxarriba).El dato hidratado es del usuario de la cookie: un navegador cuya sesión es de otro usuario arma la clave de ese usuario y pide su propio dato; el del primero nunca aparece.
Cookie vs localStorage
localStorageTokenStore (por defecto) | nextCookieTokenStore | |
|---|---|---|
| XSS | lee el token | lee el token (igual: sin HttpOnly) |
| El servidor ve la sesión | no (SSR anónimo) | sí, con readCookieTokenStore() |
| Va en todo request a la app | no | sí (incluso navegaciones que vienen de otro sitio, con SameSite=Lax) |
| CSRF | sin riesgo | el servidor de la app solo debe usar la cookie para lecturas, nunca ejecutar acciones por causa de ella |
| Tamaño | sin límite práctico | ~4 KB (los dos tokens en una sola cookie) |
| Otras pestañas | evento storage | Cookie Store API, cuando el navegador la tiene |
HTTP fuera de localhost | funciona | no funciona (el navegador descarta la cookie Secure); en http://localhost, solo donde el navegador hace una excepción (Chrome 89+, Firefox 75+) |
| Logs | no aparece | el refresh token va en todo request a Next, a los proxies y al CDN |
HTTP en desarrollo
Con Secure, todo navegador descarta la cookie en silencio en un origen HTTP que no sea localhost: la IP de la red local (http://192.168.0.10:3000) o un host de desarrollo como http://dev.operador.com:3002. Incluso http://localhost solo es una excepción donde el navegador la hace: Chrome (89+) y Firefox (75+) aceptan una cookie Secure escrita por localhost (consulta la nota del atributo Secure en Set-Cookie, en MDN); otros navegadores, como Safari, pueden no aceptarla: pruébalo en el tuyo. El navegador también descarta las cookies de más de ~4 KB. En los dos casos set comprueba si la cookie quedó y, si no, avisa con console.warn (sin el token) y no lanza un error: el inicio de sesión no queda guardado. Para probar fuera de localhost, usa HTTPS (next dev --experimental-https) o localStorageTokenStore.
Datos del jugador en el caché y en el HTML
tokenStore+next.revalidate: las respuestas del jugador (saldo, perfil, transacciones) entran en el Data Cache de Next. Quedan separadas por token (elAuthorizationentra en la clave), pero guardadas en el servidor y servidas desactualizadas al mismo jugador hasta revalidar. Para datos del jugador, dejanextfuera degetEnginexServer(y defetchOptions.next).- Prefetch de datos del jugador: con un
tokenStore, las queries de usuario entran en el estado deprefetchEnginexy, con él, en el HTML de la página (en el estado serializado, aunque el componente solo las renderice después de la hidratación, como arriba). Hazlo solo en páginas que nunca se cacheen ni se sirvan a otros usuarios (ni por Next, ni por un CDN). - Logs: saca la cookie (o el header
Cookie) de los logs de acceso de Next, del ingress y del CDN.
Migrar de localStorage a la cookie
Cambia el tokenStore y, una vez, copia la sesión existente. Borra la copia antigua solo después de comprobar que la cookie quedó (en un origen sin HTTPS no queda, y la sesión se perdería):
'use client'
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
import { nextCookieTokenStore } from '@getenginex/sdk-next'
const cookie = nextCookieTokenStore()
const legacy = localStorageTokenStore()
const tokens = legacy.get()
if (tokens && !cookie.get()) cookie.set(tokens)
if (tokens && cookie.get()?.refreshToken === tokens.refreshToken) legacy.clear()
export const enginex = createEnginexClient({ tokenStore: cookie })next.config.ts: withEnginex
// next.config.ts
import type { NextConfig } from 'next'
import { withEnginex } from '@getenginex/sdk-next/config'
const nextConfig: NextConfig = { reactStrictMode: true }
export default withEnginex(nextConfig, {
gatewayUrl: process.env.NEXT_PUBLIC_API_URL!,
paths: ['/api/:path*', '/dev/:path*'], // default: ['/api/:path*']
})- Agrega
{ source: '/api/:path*', destination: '<gatewayUrl>/api/:path*' }(uno por cada elemento depaths) después de los rewrites de la app, en un array o en{ beforeFiles, afterFiles, fallback }(entra enafterFiles). - No duplica: un rewrite de la app sin condición con el mismo
sourceprevalece. Uno conhas/missingno cubre todos los requests, y el del gateway entra después de él. - Se compone con otros wrappers: acepta el objeto de config o la función
(phase, ctx) => config. - Sin un
gatewayUrlabsoluto, lanzaCONFIGURATION_ERRORal cargar el config. - No toca
x-original-host: eso es delproxy.tsde la app.
Pruebas
- Los Client Components se prueban como en React:
@getenginex/sdk-nextreexportaEnginexProvidery los hooks, y los mocks del core (createMockFetch,createMockRealtime) reemplazan al gateway. - El código de servidor (
@getenginex/sdk-next/server) corre en Vitest con dos ajustes: haz el mock deserver-onlyy crea el cliente concreateEnginexClienty el mock en lugar degetEnginexServer(), que leeheaders()de Next y solo funciona dentro de un request.prefetchEnginexrecibe ese cliente como recibiría el del servidor:
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'
import { prefetchEnginex } from '@getenginex/sdk-next/server'
import { expect, it, vi } from 'vitest'
// The server entry imports `server-only`, which throws outside a React Server Component.
vi.mock('server-only', () => ({}))
it('prefetches the operator configuration', async () => {
// In place of getEnginexServer(), which needs Next's request headers.
const enginex = createEnginexClient({
baseUrl: 'https://gateway.test',
tenantHost: 'casino.test',
fetch: createMockFetch(),
})
const state = await prefetchEnginex(enginex, (q) => [q.config.get(), q.config.getProducts()])
expect(state.queries.map((query) => query.state.status)).toEqual(['success', 'success'])
})Para las fábricas de producto, suma las rutas del producto al mock (createMockFetch(withIgamingRoutes())) y pasa las fábricas: prefetchEnginex(createIgamingQueries(createIgaming(enginex)), (ig) => [ig.casino.listGames()]). Consulta Pruebas y mocks.