Ir para o conteúdo
Aura Logo
aurabase

Guia de roteador de aplicativo Next.js e SSR

Guia arquitetônico passo a passo para integrar Aurabase em um aplicativo Next.js 15/16 App Router com componentes de servidor, ações de servidor, middleware e sessões seguras.

Guia prático10 min lidoNível intermediárioRevisado em 19 de ago. de 2026

Esta página foi traduzida automaticamente. A versão em inglês é oficial.

O modelo Aurabase SSR#

Em aplicativos modernos renderizados no lado do servidor, o estado de autenticação do usuário não pode ser armazenado no localStorage do navegador (inacessível pelo servidor). Aurabase sincroniza automaticamente a sessão em cookies HTTP seguros.

Isolamento total da consulta

createServerClient não tem estado compartilhado na memória. Cada solicitação do servidor instancia um cliente isolado conectado aos cabeçalhos HTTP da solicitação, garantindo estanqueidade absoluta entre os usuários (risco zero de vazamentos de sessão).

Os 3 pilares do App Router#

proxy.tstypescript
import { createServerClient } from '@aurabase/aurabase-js/ssr'
import { NextResponse, type NextRequest } from 'next/server'

// Next.js 16: este arquivo é `proxy.ts` e a função se chama `proxy`.
// Next.js 15: nomeie o arquivo `middleware.ts` e a função `middleware`.
export async function proxy(request: NextRequest) {
  const response = NextResponse.next({ request })
  const aura = createServerClient(
    process.env.NEXT_PUBLIC_AURABASE_URL!,
    process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
    {
      cookies: {
        getAll() { return request.cookies.getAll() },
        setAll(cookies) {
          cookies.forEach(({ name, value, options }) => {
            request.cookies.set(name, value)
            response.cookies.set(name, value, options)
          })
        },
      },
    })

  const { data: user } = await aura.auth.getUser()
  if (!user && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  return response
}

Gerenciamento automático de Multi-Chunking#

Os navegadores da Web limitam o tamanho de um cookie a aproximadamente 4 KB. Quando um token JWT ou metadados de usuário excede esse limite, o módulo @aurabase/aurabase-js/ssr divide automaticamente a carga em vários cookies numerados:

  • aura-<scope>-auth.0 (primeiros 3600 bytes)
  • aura-<scope>-auth.1 (resto da sessão)

Após a leitura, o servidor remonta fielmente os pedaços para restaurar o estado sem qualquer perda de dados ou interrupção da sessão.

Regras de ouro na produção#

Atributos HttpOnly e SameSite

Os cookies de token de atualização nunca devem ser expostos ao JavaScript do cliente para evitar ataques XSS.

Serviço de chave de função estritamente servidor

NUNCA passe seu AURABASE_SERVICE_ROLE_KEY para createBrowserClient ou componentes com a diretiva "use client".

Atualizar no Middleware

Chame getUser() no proxy (middleware.ts em Next.js 15): ele renova os tokens antes que expirem e pergunta ao servidor quem é o usuário. Nunca autorize uma solicitação do servidor com getSession(): no servidor ele apenas lê o cookie, que o navegador pode falsificar.

Para ir mais longe#