Aurabase Logo
aurabasedocs
docs›Guides›Next.js App Router & SSR

Next.js App Router & SSR Guide

Step-by-step architectural guide to integrating Aurabase into a Next.js 14/15 App Router application with Server Components, Server Actions, Middleware and secure sessions.

10 min read·Level intermediate·Revised on Aug 19, 2026
This English text was generated automatically from the French original and has not been reviewed yet.
#
Architecture

The Aurabase SSR model

In modern server-side rendered applications, the user's authentication state cannot be stored in the browser's localStorage (inaccessible by the server). Aurabase automatically synchronizes the session in secure HTTP cookies.

Full query isolation

createServerClient is without shared state in memory. Each server request instantiates an isolated client connected to the HTTP headers of the request, guaranteeing absolute tightness between users (zero risk of session leaks).

#
Implementation

The 3 pillars App Router

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

export async function middleware(request: NextRequest) {
  let response = NextResponse.next({ request })
  const aura = createServerClient(
    process.env.NEXT_PUBLIC_AURA_URL!,
    process.env.NEXT_PUBLIC_AURA_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 { user } = await aura.auth.getUser()
  if (!user && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  return response
}
#
Cookies

Automatic management of Multi-Chunking

Web browsers limit the size of a cookie to approximately 4 KB. When a JWT token or user metadata exceeds this limit, the @aurabase/aurabase-js/ssr module automatically splits the load into several numbered cookies:

  • aura-[project_id]-auth.0 (first 3600 bytes)
  • aura-[project_id]-auth.1 (rest of session)

Upon reading, the server faithfully reassembles the chunks in order to restore the state without any data loss or session interruption.

#
Security

Golden rules in production

HttpOnly & SameSite attributes

Refresh token cookies should never be exposed to client JavaScript to prevent XSS attacks.

Role Key service strictly server

NEVER pass your SERVICE_ROLE_KEY into createBrowserClient or components with the "use client" directive.

Refresh in Middleware

Always call getSession() or getUser() in the middleware to renew tokens before they expire.

Last updated · Aug 19, 2026