Next.js
@getenginex/sdk-next é o adapter do App Router. Ele tem três entries:
| Entry | Onde roda | O que traz |
|---|---|---|
@getenginex/sdk-next | Client Components | tudo do @getenginex/sdk-react e o nextCookieTokenStore (sessão em cookie, opcional) |
@getenginex/sdk-next/server | Server Components, Server Actions, Route Handlers (server-only) | getEnginexServer, prefetchEnginex e readCookieTokenStore |
@getenginex/sdk-next/config | next.config.ts | withEnginex, o rewrite /api/:path* → gateway |
npm i @getenginex/sdk @getenginex/sdk-next @tanstack/react-queryPeers: next >=15, react >=19, @tanstack/react-query ^5 e @getenginex/sdk >=0.6.0 <1.0.0. O sdk-react vem como dependência (mesma versão do sdk-next). Importar @getenginex/sdk-next/server num Client Component quebra o build (server-only).
O modelo é o dos players: SSR anônimo e por tenant (configuração, catálogo, CMS), sessão no browser (localStorage) e o browser chamando o gateway pela mesma origem (/api, via rewrite).
Cliente
O provider é o mesmo do React. Crie o client do browser num 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>
)
}No browser o SDK chama /api/v1/... na mesma origem e manda o domínio da página como tenant; o rewrite (abaixo) leva o request ao 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:
baseUrlda opção ou a variávelENGINEX_GATEWAY_URL, lida a cada request (URL absoluta). Sem as duas, a promise rejeita comCONFIGURATION_ERRORantes de qualquerfetch. Se o app já tem a URL emNEXT_PUBLIC_API_URL, definaENGINEX_GATEWAY_URLcom o mesmo valor (ou passebaseUrl: process.env.NEXT_PUBLIC_API_URL). - Um client por request, memoizado com o
cache()do React: na mesma request, opções iguais devolvem o mesmo client (tagscomparadas pelo conteúdo,resolveHostetokenStorepela referência, então defina-os fora do componente). Requests diferentes nunca compartilham client, e não há client em escopo de módulo. Fora de um render do React (Route Handler), cada chamada cria um client novo. - Não coloque o
sdk-nextemserverExternalPackages: fora do bundle do servidor, o import deserver-onlydo entry/serverfalha e onext buildpara com o erro doserver-only(conferido com Turbopack e webpack). Deixe o Next empacotar osdk-next. - Anônimo por padrão: não lê cookies, usa um
memoryTokenStore()vazio eautoRefresh: false. As queries de usuário feitas com ele rejeitam comUNAUTHENTICATEDsem request. - Cache do Next:
next: { revalidate, tags }vai em todofetchdo client; umfetchOptions.nextnuma chamada vence campo a campo. A chave do Data Cache inclui os headers do request, então tenants (X-Original-Hostenviado ao gateway) e tokens (Authorization) diferentes nunca dividem resposta. - Ler
headers()torna a rota dinâmica, como qualquer dado por tenant.
Tenant
O domínio do operador sai de headers(), nesta ordem:
host: o domínio que o browser pediu;x-forwarded-host: último recurso.
É o que os players já fazem no SSR. De uma lista (a.com, proxy.interno), vale o primeiro valor; a porta fica como veio (o gateway a remove). Sem nenhum dos dois, rejeita com CONFIGURATION_ERROR.
| Opção | Efeito |
|---|---|
trustOriginalHost: true | x-original-host passa a vir antes de host. Só com um proxy.ts que o sobrescreve em toda request que renderiza (abaixo). |
resolveHost(headers) | troca a descoberta por inteiro (ignora a ordem e trustOriginalHost); devolver undefined rejeita com CONFIGURATION_ERROR. |
x-original-host vem do browser
Numa request de página, o x-original-host chega como o browser mandou: o proxy.ts dos players só o sobrescreve em /api e /dev. Confiar nele sem um proxy.ts que o grave em toda request deixaria qualquer um escolher o operador do SSR: a página de um domínio renderizaria com a configuração, o catálogo e o CMS de outro operador (e, com next.revalidate, guardaria essas respostas no Data Cache).
proxy.ts com x-original-host
O gateway acha o operador pelo X-Original-Host. Os requests do browser passam pelo rewrite /api, e o proxy.ts do app (o middleware.ts antes do Next 16) grava o header com o host da página. Para também ligar trustOriginalHost, o proxy.ts precisa sobrescrever o header em toda request que renderiza, não só em /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 })Se um ingress reescreve o Host para um nome interno (ex.: player.default.svc.cluster.local), a ordem padrão pega esse nome. Nesse caso use resolveHost com o header em que o ingress guarda o domínio público, ou grave esse header como x-original-host no proxy.ts acima (no lugar de host) e ligue 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 })Confira em produção qual header traz o domínio público antes de escolher: depende do 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>
)
}selectrecebe as fábricas do core (com o client do servidor) ou as de um pacote de produto. As chaves são as mesmas queuseEnginexQueryusa no browser, então o componente encontra o dado 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(), ])Um
QueryClientnovo por chamada, sem retry, descartado no fim (nada fica entre requests).Uma fábrica que falha não derruba as outras e fica fora do estado: só queries com sucesso são desidratadas, nunca um erro. O browser busca as que faltaram. Com o client anônimo, as queries de usuário ficam de fora (sem request).
staleTime: o estado desidratado leva só a chave e o dado. Quem decide se o browser busca de novo logo ao montar é ostaleTimedoQueryClientdo browser: o que oEnginexProvidercria usa 60 s; no seu, use um acima de zero (os players usam 5 min). Com o padrão do TanStack (0), o browser refaz tudo logo depois de hidratar (menosconfig.*, que temstaleTimepróprio).
Sessão em cookie (opcional)
O padrão continua sendo a sessão no localStorage e o SSR anônimo. Com a sessão em cookie, o servidor também a lê, para páginas com dados do jogador renderizadas no 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, semDomain.name,maxAge(segundos; sem ele, cookie de sessão do browser) epathsão opções; use o mesmonamenoreadCookieTokenStore({ name }). Valores inválidos lançamCONFIGURATION_ERRORna criação. - Sem
HttpOnly, de propósito: o refresh da sessão e o?token=do WebSocket precisam do token em JavaScript. - Servidor só lê: Server Components não gravam cookies. Quem renova e regrava a sessão é o browser; um access token vencido faz as chamadas do servidor falharem com
UNAUTHENTICATEDaté lá. initialSession: só para a parte da tela que depende só da sessão (cabeçalho com o botão de sair, menu do jogador): passe aoEnginexProvidera sessão lida no servidor (enginex.session.get()do client com oreadCookieTokenStore()), num Client Component que a recebe por prop, e o servidor e a hidratação renderizam a mesma sessão. Não envolva com uminitialSessionautenticado componentes que renderizam queries de usuário do SDK no SSR (veja abaixo).- Fora do browser (o SSR de um Client Component), o
nextCookieTokenStorenão guarda nada.
Dados do jogador: Server Component ou depois da hidratação
As fábricas montam a chave de uma query de usuário com a sessão do client do browser (client.session), não com o initialSession. No SSR de um Client Component esse client não tem sessão (o nextCookieTokenStore não lê nada sem document), então q.wallet.getBalance() renderizado no servidor usa a chave 'anonymous': o HTML sai sem o dado do prefetch e a hidratação falha (o browser renderiza a chave do jogador, com o dado). Por isso:
Em Client Components, renderize queries de usuário só depois da hidratação: condicione o componente ao
useSession()autenticado, com oinitialSessionpadrão (anônimo), como oAccountdo exemplo. O servidor e a hidratação renderizam o ramo anônimo; logo depois a sessão real aparece e o componente monta. Se oprefetchEnginextrouxe o dado do jogador (comreadCookieTokenStore()), esse primeiro render do cliente já o usa, sem request.tsx'use client' function Account() { const session = useSession() return session.status === 'authenticated' ? <Wallet /> : <LoginForm /> }No HTML do servidor, renderize os dados do jogador num Server Component (
getEnginexServer({ tokenStore: await readCookieTokenStore() }), comoapp/account/page.tsxacima).O dado hidratado é do usuário do cookie: um browser cuja sessão é de outro usuário monta a chave dele e busca o próprio dado; o do primeiro nunca aparece.
Cookie × localStorage
localStorageTokenStore (padrão) | nextCookieTokenStore | |
|---|---|---|
| XSS | lê o token | lê o token (igual: sem HttpOnly) |
| Servidor vê a sessão | não (SSR anônimo) | sim, com readCookieTokenStore() |
| Vai em toda request ao app | não | sim (inclusive navegações vindas de outro site, com SameSite=Lax) |
| CSRF | sem risco | o servidor do app só deve usar o cookie para leituras, nunca executar ações por causa dele |
| Tamanho | sem limite prático | ~4 KB (os dois tokens num cookie só) |
| Outras abas | evento storage | Cookie Store API, quando o browser tem |
HTTP fora de localhost | funciona | não funciona (o browser descarta o cookie Secure); em http://localhost, só onde o browser abre exceção (Chrome 89+, Firefox 75+) |
| Logs | não aparece | o refresh token vai em toda request ao Next, aos proxies e à CDN |
HTTP em desenvolvimento
Com Secure, todo browser descarta o cookie em silêncio numa origem HTTP que não seja localhost: IP da rede local (http://192.168.0.10:3000) ou um host de desenvolvimento como http://dev.operador.com:3002. Mesmo http://localhost só é exceção onde o browser a abre: Chrome (89+) e Firefox (75+) aceitam um cookie Secure gravado por localhost (veja a nota do atributo Secure em Set-Cookie, no MDN); outros browsers, como o Safari, podem não aceitar: teste no seu. O browser também descarta cookies acima de ~4 KB. Nos dois casos o set confere se o cookie ficou e, se não, avisa com console.warn (sem o token) e não lança: o login não fica gravado. Para testar fora de localhost, use HTTPS (next dev --experimental-https) ou o localStorageTokenStore.
Dados do jogador no cache e no HTML
tokenStore+next.revalidate: as respostas do jogador (saldo, perfil, transações) entram no Data Cache do Next. Ficam separadas por token (oAuthorizationentra na chave), mas guardadas no servidor e servidas velhas ao mesmo jogador até revalidar. Para dados do jogador, deixenextde fora dogetEnginexServer(e defetchOptions.next).- Prefetch de dados do jogador: com um
tokenStore, as queries de usuário entram no estado doprefetchEnginexe, com ele, no HTML da página (no estado serializado, mesmo que o componente só as renderize depois da hidratação, como acima). Só faça isso em páginas nunca cacheadas e servidas a outros usuários (nem pelo Next, nem por uma CDN). - Logs: tire o cookie (ou o header
Cookie) dos logs de acesso do Next, do ingress e da CDN.
Migrar do localStorage para o cookie
Troque o tokenStore e, uma vez, copie a sessão existente. Só apague a cópia antiga depois de conferir que o cookie ficou (numa origem sem HTTPS ele não fica, e a sessão se perderia):
'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*']
})- Acrescenta
{ source: '/api/:path*', destination: '<gatewayUrl>/api/:path*' }(um por item depaths) depois dos rewrites do app, em array ou em{ beforeFiles, afterFiles, fallback }(entra emafterFiles). - Não duplica: um rewrite do app sem condição com o mesmo
sourcevence. Um comhas/missingnão cobre todas as requests, e o do gateway entra depois dele. - Compõe com outros wrappers: aceita o objeto de config ou a função
(phase, ctx) => config. - Sem
gatewayUrlabsoluto, lançaCONFIGURATION_ERRORao carregar o config. - Não mexe no
x-original-host: isso é doproxy.tsdo app.
Testes
- Client Components são testados como no React:
@getenginex/sdk-nextreexporta oEnginexProvidere os hooks, e os mocks do core (createMockFetch,createMockRealtime) fazem o papel do gateway. - Código de servidor (
@getenginex/sdk-next/server) roda no Vitest com dois ajustes: faça o mock deserver-onlye crie o cliente comcreateEnginexCliente o mock em vez degetEnginexServer(), que lê oheaders()do Next e só funciona dentro de um request.prefetchEnginexrecebe esse cliente como receberia o do 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 fábricas de produto, some as rotas do produto ao mock (createMockFetch(withIgamingRoutes())) e passe as fábricas: prefetchEnginex(createIgamingQueries(createIgaming(enginex)), (ig) => [ig.casino.listGames()]). Veja Testes e mocks.