| name | nuxt-better-auth |
| description | Use when implementing auth in Nuxt apps with @onmax/nuxt-better-auth - provides useUserSession composable, server auth helpers, route protection, and Better Auth plugins integration. |
| license | MIT |
Nuxt Better Auth
Authentication module for Nuxt 4+ built on Better Auth. It adds Nuxt-specific setup, route protection, server helpers, and typed auth state.
Alpha status: the package is still pre-stable. Verify behavior against the current docs and source before relying on edge cases.
When to Use
- Installing/configuring
@onmax/nuxt-better-auth
- Implementing sign-in, sign-up, or sign-out 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
Available Guidance
| File | Topics |
|---|
| references/installation.md | install flow, env vars, config files |
| references/client-auth.md | useUserSession, client methods, redirects, loading states |
| references/server-auth.md | serverAuth, getUserSession, getRequestSession, requireUserSession |
| references/route-protection.md | route rules, page meta, API protection |
| references/plugins.md | plugin pairing between server and client |
| references/database.md | NuxtHub schema generation, secondary storage |
| references/client-only.md | external Better Auth backends and clientOnly mode |
| references/types.md | public auth types and augmentation |
Usage Pattern
Do not load every reference file by default. Pick the smallest file that matches the task.
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
const { user, loggedIn, signIn, signOut } = useUserSession()
await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })
const { user } = await requireUserSession(event, { user: { role: 'admin' } })
routeRules: {
'/admin/**': { auth: { user: { role: 'admin' } } },
'/login': { auth: 'guest' },
'/app/**': { auth: 'user' }
}
Resources