Next.js App Router & SSR Guide
Step-by-step architectural guide to integrating Aurabase into a Next.js 15/16 App Router application with Server Components, Server Actions, Middleware and secure sessions.
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.
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).
The 3 pillars 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
}
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-<scope>-auth.0(first 3600 bytes)aura-<scope>-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.
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 AURABASE_SERVICE_ROLE_KEY into createBrowserClient or components with the "use client" directive.
Refresh in Middleware
Call getUser() in the proxy (middleware.ts on Next.js 15): it renews the tokens before they expire and asks the server who the user is. Never authorize a server request with getSession(): on the server it only reads the cookie, which the browser can forge.