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