Getting Started

How It Works

Understand the architecture after completing setup.

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()`, `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