Nuxt Better Auth

Authentication module for Nuxt 4+ built on Better Auth. Provides composables, server utilities, and route protection.

Alpha Status: This module is currently in alpha (v0.0.2-alpha.14) and not recommended for production use. APIs may change.

When to Use

Installing/configuring @onmax/nuxt-better-auth
Implementing login/signup/signout flows
Protecting routes (client and server)
Accessing user session in API routes
Integrating Better Auth plugins (admin, passkey, 2FA)
Setting up database with NuxtHub
Using clientOnly mode for external auth backends

For Nuxt patterns: use nuxt skill For NuxtHub database: use nuxthub skill

Available Guidance

File	Topics
references/installation.md	Module setup, env vars, config files
references/client-auth.md	useUserSession, signIn/signUp/signOut, BetterAuthState, safe redirects
references/server-auth.md	serverAuth, getUserSession, requireUserSession
references/route-protection.md	routeRules, definePageMeta, middleware
references/plugins.md	Better Auth plugins (admin, passkey, 2FA)
references/database.md	NuxtHub integration, Drizzle schema, custom tables with FKs
references/client-only.md	External auth backend, clientOnly mode, CORS
references/types.md	AuthUser, AuthSession, type augmentation

Usage Pattern

Load based on context:

Installing module? → references/installation.md
Login/signup forms? → references/client-auth.md
API route protection? → references/server-auth.md
Route rules/page meta? → references/route-protection.md
Using plugins? → references/plugins.md
Database setup? → references/database.md
External auth backend? → references/client-only.md
TypeScript types? → references/types.md

DO NOT read all files at once. Load based on context.

Key Concepts

Concept	Description
`useUserSession()`	Client composable - user, session, loggedIn, signIn/Out methods
`requireUserSession()`	Server helper - throws 401/403 if not authenticated
`auth` route mode	`'user'`, `'guest'`, `{ user: {...} }`, or `false`
`serverAuth()`	Get Better Auth instance in server routes

Quick Reference

// Client: useUserSession()
const { user, loggedIn, signIn, signOut } = useUserSession()
await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })

// Server: requireUserSession()
const { user } = await requireUserSession(event, { user: { role: 'admin' } })

// nuxt.config.ts: Route protection
routeRules: {
  '/admin/**': { auth: { user: { role: 'admin' } } },
  '/login': { auth: 'guest' },
  '/app/**': { auth: 'user' }
}

Resources

Token efficiency: Main skill ~300 tokens, each sub-file ~800-1200 tokens