Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

Next.js ​

@getenginex/sdk-next es el adapter del App Router. Tiene tres entries:

EntryDónde correQué incluye
@getenginex/sdk-nextClient Componentstodo lo de @getenginex/sdk-react y nextCookieTokenStore (sesión en cookie, opcional)
@getenginex/sdk-next/serverServer Components, Server Actions, Route Handlers (server-only)getEnginexServer, prefetchEnginex y readCookieTokenStore
@getenginex/sdk-next/confignext.config.tswithEnginex, el rewrite /api/:path* → gateway
bash
npm i @getenginex/sdk @getenginex/sdk-next @tanstack/react-query

Peers: 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':

tsx
// 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>
}
tsx
// 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 ​

tsx
// 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>
}
bash
# server .env (no NEXT_PUBLIC_)
ENGINEX_GATEWAY_URL=https://gateway.operador.com
  • Gateway: el baseUrl de la opción o la variable ENGINEX_GATEWAY_URL, leída en cada request (URL absoluta). Sin ninguna de las dos, la promise rechaza con CONFIGURATION_ERROR antes de cualquier fetch. Si la app ya tiene la URL en NEXT_PUBLIC_API_URL, define ENGINEX_GATEWAY_URL con el mismo valor (o pasa baseUrl: 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 (tags comparadas por contenido, resolveHost y tokenStore por 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-next en serverExternalPackages: fuera del bundle del servidor, el import de server-only del entry /server falla y next build se detiene con el error de server-only (verificado con Turbopack y webpack). Deja que Next empaquete sdk-next.
  • Anónimo por defecto: no lee cookies, usa un memoryTokenStore() vacío y autoRefresh: false. Las queries de usuario hechas con él rechazan con UNAUTHENTICATED sin request.
  • Caché de Next: next: { revalidate, tags } va en todo fetch del cliente; un fetchOptions.next en una llamada prevalece campo a campo. La clave del Data Cache incluye los headers del request, así que tenants (X-Original-Host enviado 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:

  1. host: el dominio que pidió el navegador;
  2. 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ónEfecto
trustOriginalHost: truex-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:

ts
// 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).*)'],
}
ts
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:

ts
// 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 ​

tsx
// 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>
  )
}
  • select recibe las fábricas del core (con el cliente del servidor) o las de un paquete de producto. Las claves son las mismas que usa useEnginexQuery en el navegador, así que el componente encuentra el dato hidratado:

    ts
    import { 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 QueryClient nuevo 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 el staleTime del QueryClient del navegador: el que crea EnginexProvider usa 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 (menos config.*, que tiene staleTime propio).

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:

tsx
// 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 }) })
tsx
// 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, sin Domain. name, maxAge (segundos; sin él, cookie de sesión del navegador) y path son opciones; usa el mismo name en readCookieTokenStore({ name }). Los valores inválidos lanzan CONFIGURATION_ERROR en 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 UNAUTHENTICATED hasta 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 al EnginexProvider la sesión leída en el servidor (enginex.session.get() del cliente con el readCookieTokenStore()), en un Client Component que la reciba por prop, y el servidor y la hidratación renderizan la misma sesión. No envuelvas con un initialSession autenticado componentes que renderizan queries de usuario del SDK en el SSR (ver abajo).
  • Fuera del navegador (el SSR de un Client Component), nextCookieTokenStore no 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 el initialSession por defecto (anónimo), como el Account del ejemplo. El servidor y la hidratación renderizan la rama anónima; enseguida aparece la sesión real y el componente se monta. Si prefetchEnginex trajo el dato del jugador (con readCookieTokenStore()), 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() }), como app/account/page.tsx arriba).

  • 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.

localStorageTokenStore (por defecto)nextCookieTokenStore
XSSlee el tokenlee el token (igual: sin HttpOnly)
El servidor ve la sesiónno (SSR anónimo)sí, con readCookieTokenStore()
Va en todo request a la appnosí (incluso navegaciones que vienen de otro sitio, con SameSite=Lax)
CSRFsin riesgoel servidor de la app solo debe usar la cookie para lecturas, nunca ejecutar acciones por causa de ella
Tamañosin límite práctico~4 KB (los dos tokens en una sola cookie)
Otras pestañasevento storageCookie Store API, cuando el navegador la tiene
HTTP fuera de localhostfuncionano funciona (el navegador descarta la cookie Secure); en http://localhost, solo donde el navegador hace una excepción (Chrome 89+, Firefox 75+)
Logsno apareceel 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 (el Authorization entra en la clave), pero guardadas en el servidor y servidas desactualizadas al mismo jugador hasta revalidar. Para datos del jugador, deja next fuera de getEnginexServer (y de fetchOptions.next).
  • Prefetch de datos del jugador: con un tokenStore, las queries de usuario entran en el estado de prefetchEnginex y, 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.

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):

ts
'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 ​

ts
// 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 de paths) después de los rewrites de la app, en un array o en { beforeFiles, afterFiles, fallback } (entra en afterFiles).
  • No duplica: un rewrite de la app sin condición con el mismo source prevalece. Uno con has/missing no 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 gatewayUrl absoluto, lanza CONFIGURATION_ERROR al cargar el config.
  • No toca x-original-host: eso es del proxy.ts de la app.

Pruebas ​

  • Los Client Components se prueban como en React: @getenginex/sdk-next reexporta EnginexProvider y 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 de server-only y crea el cliente con createEnginexClient y el mock en lugar de getEnginexServer(), que lee headers() de Next y solo funciona dentro de un request. prefetchEnginex recibe ese cliente como recibiría el del servidor:
ts
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.