Skip to content
Aurabase Logo
aurabase

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.

How-to guide10 min readLevel intermediateRevised on Aug 19, 2026

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

The 3 pillars 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
}

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.

To go further#