Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

Next.js ​

@getenginex/sdk-next é o adapter do App Router. Ele tem três entries:

EntryOnde rodaO que traz
@getenginex/sdk-nextClient Componentstudo do @getenginex/sdk-react e o nextCookieTokenStore (sessão em cookie, opcional)
@getenginex/sdk-next/serverServer Components, Server Actions, Route Handlers (server-only)getEnginexServer, prefetchEnginex e readCookieTokenStore
@getenginex/sdk-next/confignext.config.tswithEnginex, o rewrite /api/:path* → gateway
bash
npm i @getenginex/sdk @getenginex/sdk-next @tanstack/react-query

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

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

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 ​

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: baseUrl da opção ou a variável ENGINEX_GATEWAY_URL, lida a cada request (URL absoluta). Sem as duas, a promise rejeita com CONFIGURATION_ERROR antes de qualquer fetch. Se o app já tem a URL em NEXT_PUBLIC_API_URL, defina ENGINEX_GATEWAY_URL com o mesmo valor (ou passe baseUrl: 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 (tags comparadas pelo conteúdo, resolveHost e tokenStore pela 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-next em serverExternalPackages: fora do bundle do servidor, o import de server-only do entry /server falha e o next build para com o erro do server-only (conferido com Turbopack e webpack). Deixe o Next empacotar o sdk-next.
  • Anônimo por padrão: não lê cookies, usa um memoryTokenStore() vazio e autoRefresh: false. As queries de usuário feitas com ele rejeitam com UNAUTHENTICATED sem request.
  • Cache do Next: next: { revalidate, tags } vai em todo fetch do client; um fetchOptions.next numa chamada vence campo a campo. A chave do Data Cache inclui os headers do request, então tenants (X-Original-Host enviado 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:

  1. host: o domínio que o browser pediu;
  2. 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çãoEfeito
trustOriginalHost: truex-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:

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

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:

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

Confira em produção qual header traz o domínio público antes de escolher: depende do 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 recebe as fábricas do core (com o client do servidor) ou as de um pacote de produto. As chaves são as mesmas que useEnginexQuery usa no browser, então o componente encontra o dado 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(),
    ])
  • Um QueryClient novo 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 é o staleTime do QueryClient do browser: o que o EnginexProvider cria 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 (menos config.*, que tem staleTime próprio).

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:

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, sem Domain. name, maxAge (segundos; sem ele, cookie de sessão do browser) e path são opções; use o mesmo name no readCookieTokenStore({ name }). Valores inválidos lançam CONFIGURATION_ERROR na 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 UNAUTHENTICATED até 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 ao EnginexProvider a sessão lida no servidor (enginex.session.get() do client com o readCookieTokenStore()), num Client Component que a recebe por prop, e o servidor e a hidratação renderizam a mesma sessão. Não envolva com um initialSession autenticado componentes que renderizam queries de usuário do SDK no SSR (veja abaixo).
  • Fora do browser (o SSR de um Client Component), o nextCookieTokenStore nã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 o initialSession padrão (anônimo), como o Account do exemplo. O servidor e a hidratação renderizam o ramo anônimo; logo depois a sessão real aparece e o componente monta. Se o prefetchEnginex trouxe o dado do jogador (com readCookieTokenStore()), 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() }), como app/account/page.tsx acima).

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

localStorageTokenStore (padrão)nextCookieTokenStore
XSSlê o tokenlê o token (igual: sem HttpOnly)
Servidor vê a sessãonão (SSR anônimo)sim, com readCookieTokenStore()
Vai em toda request ao appnãosim (inclusive navegações vindas de outro site, com SameSite=Lax)
CSRFsem riscoo servidor do app só deve usar o cookie para leituras, nunca executar ações por causa dele
Tamanhosem limite prático~4 KB (os dois tokens num cookie só)
Outras abasevento storageCookie Store API, quando o browser tem
HTTP fora de localhostfuncionanão funciona (o browser descarta o cookie Secure); em http://localhost, só onde o browser abre exceção (Chrome 89+, Firefox 75+)
Logsnão apareceo 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 (o Authorization entra na chave), mas guardadas no servidor e servidas velhas ao mesmo jogador até revalidar. Para dados do jogador, deixe next de fora do getEnginexServer (e de fetchOptions.next).
  • Prefetch de dados do jogador: com um tokenStore, as queries de usuário entram no estado do prefetchEnginex e, 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.

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

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*']
})
  • Acrescenta { source: '/api/:path*', destination: '<gatewayUrl>/api/:path*' } (um por item de paths) depois dos rewrites do app, em array ou em { beforeFiles, afterFiles, fallback } (entra em afterFiles).
  • Não duplica: um rewrite do app sem condição com o mesmo source vence. Um com has/missing nã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 gatewayUrl absoluto, lança CONFIGURATION_ERROR ao carregar o config.
  • Não mexe no x-original-host: isso é do proxy.ts do app.

Testes ​

  • Client Components são testados como no React: @getenginex/sdk-next reexporta o EnginexProvider e 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 de server-only e crie o cliente com createEnginexClient e o mock em vez de getEnginexServer(), que lê o headers() do Next e só funciona dentro de um request. prefetchEnginex recebe esse cliente como receberia o do 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 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.