Guide Next.js App Router & SSR
Guide architectural pas-à-pas pour intégrer Aurabase dans une application Next.js 15/16 App Router avec Server Components, Server Actions, Middleware et sessions sécurisées.
Le modèle SSR d'Aurabase#
Dans les applications modernes rendues côté serveur, l'état d'authentification de l'utilisateur ne peut pas être stocké dans le localStorage du navigateur (inaccessible par le serveur). Aurabase synchronise automatiquement la session dans des cookies HTTP sécurisés.
createServerClient est sans état partagé en mémoire. Chaque requête serveur instancie un client isolé branché sur les en-têtes HTTP de la requête, garantissant une étanchéité absolue entre utilisateurs (zéro risque de fuite de session).
Les 3 piliers App Router#
import { createServerClient } from '@aurabase/aurabase-js/ssr'
import { NextResponse, type NextRequest } from 'next/server'
// Next.js 16: this file is `proxy.ts` and the function is named `proxy`.
// Next.js 15: name the file `middleware.ts` and the function `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
}
Gestion automatique du Multi-Chunking#
Les navigateurs web limitent la taille d'un cookie à environ 4 Ko. Lorsqu'un token JWT ou les métadonnées de l'utilisateur dépassent cette limite, le module @aurabase/aurabase-js/ssr découpe automatiquement la charge en plusieurs cookies numérotés :
aura-<scope>-auth.0(3600 premiers octets)aura-<scope>-auth.1(reste de la session)
À la lecture, le serveur réassemble fidèlement les chunks dans l'ordre pour restaurer l'état sans aucune perte de données ni coupure de session.
Règles d’or en production#
Attributs HttpOnly & SameSite
Les cookies de refresh token ne doivent jamais être exposés au JavaScript client pour prévenir les attaques XSS.
Service Role Key strictement serveur
Ne passez JAMAIS votre AURABASE_SERVICE_ROLE_KEY dans createBrowserClient ou des composants avec la directive "use client".
Rafraîchissement dans le Middleware
Appelez getUser() dans le proxy (middleware.ts sur Next.js 15) : il renouvelle les jetons avant leur expiration et demande au serveur qui est l’utilisateur. N’autorisez jamais une requête serveur avec getSession() : côté serveur, elle lit seulement le cookie, que le navigateur peut forger.