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 Module Docs Better Auth Docs
Token efficiency: Main skill ~300 tokens, each sub-file ~800-1200 tokens