Aller au contenu
Logo Aurabase
aurabase

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.

Guide pratique10 min de lectureNiveau intermédiaireRévisé le 19 août 2026

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.

Isolation totale des requêtes

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#

proxy.tstypescript
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.

Pour aller plus loin#