Getting Started

How It Works

Understand the architecture after completing setup.

Use this page after installation. It explains how the module connects Nuxt runtime behavior to Better Auth rather than walking through setup again.

Architecture

Initialization

During build, the module reads server/auth.config.ts and generates the auth handler. If using NuxtHub, it also generates the database schema automatically.

The module injects a catch-all API handler at /api/auth/**. This handler processes all authentication requests (login, logout, session fetching) using the configuration provided in server/auth.config.ts.

Client Runtime

On the client side, useUserSession initializes the Better Auth client. It establishes a reactive connection to the session state, ensuring that your UI updates immediately when a user logs in or out.

Key Responsibilities

Feature	What it provides	Side
Server handler	Mounts Better Auth at `/api/auth/*`	Server
Composables	`useUserSession()` for reactive state	Client
Server utils	`serverAuth(event?)`, `getUserSession(event)`, etc.	Server
Route protection	`routeRules.auth` and `definePageMeta({ auth })`	Both
Type augmentation	Inferred `AuthUser` and `AuthSession` types	Build

Request Flow

User visits a protected page
Route middleware checks auth rule in routeRules or page meta
If not authenticated, redirects to login page
User submits credentials to /api/auth/sign-in/email
Better Auth validates credentials and creates session
Session cookie is set, user redirected to original page
useUserSession() reads session from cookie, updates reactive state

What this means in practice

client pages use useUserSession() and related composables
protected API routes should still call requireUserSession(event)
route rules improve navigation UX, but server-side checks remain the real security boundary
NuxtHub integration and schema generation are build-time concerns, not request-time concerns