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.8) 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
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, 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 |
| 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
- 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
1---2name: nuxt-better-auth3description: 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.4license: MIT5---6
7# Nuxt Better Auth
8
9Authentication module for Nuxt 4+ built on [Better Auth](https://www.better-auth.com/). Provides composables, server utilities, and route protection.
10
11> **Alpha Status**: This module is currently in alpha (v0.0.2-alpha.8) and not recommended for production use. APIs may change.
12
13## When to Use
14
15- Installing/configuring `@onmax/nuxt-better-auth`
16- Implementing login/signup/signout flows
17- Protecting routes (client and server)
18- Accessing user session in API routes
19- Integrating Better Auth plugins (admin, passkey, 2FA)
20- Setting up database with NuxtHub
21
22**For Nuxt patterns:** use `nuxt` skill
23**For NuxtHub database:** use `nuxthub` skill
24
25## Available Guidance
26
27| File | Topics |
28| -------------------------------------------------------------------- | ----------------------------------------------------- |
29| **[references/installation.md](references/installation.md)** | Module setup, env vars, config files |
30| **[references/client-auth.md](references/client-auth.md)** | useUserSession, signIn/signUp/signOut, safe redirects |
31| **[references/server-auth.md](references/server-auth.md)** | serverAuth, getUserSession, requireUserSession |
32| **[references/route-protection.md](references/route-protection.md)** | routeRules, definePageMeta, middleware |
33| **[references/plugins.md](references/plugins.md)** | Better Auth plugins (admin, passkey, 2FA) |
34| **[references/database.md](references/database.md)** | NuxtHub integration, Drizzle schema |
35| **[references/types.md](references/types.md)** | AuthUser, AuthSession, type augmentation |
36
37## Usage Pattern
38
39**Load based on context:**
40
41- Installing module? → [references/installation.md](references/installation.md)
42- Login/signup forms? → [references/client-auth.md](references/client-auth.md)
43- API route protection? → [references/server-auth.md](references/server-auth.md)
44- Route rules/page meta? → [references/route-protection.md](references/route-protection.md)
45- Using plugins? → [references/plugins.md](references/plugins.md)
46- Database setup? → [references/database.md](references/database.md)
47- TypeScript types? → [references/types.md](references/types.md)
48
49**DO NOT read all files at once.** Load based on context.
50
51## Key Concepts
52
53| Concept | Description |
54| ---------------------- | --------------------------------------------------------------- |
55| `useUserSession()` | Client composable - user, session, loggedIn, signIn/Out methods |
56| `requireUserSession()` | Server helper - throws 401/403 if not authenticated |
57| `auth` route mode | `'user'`, `'guest'`, `{ user: {...} }`, or `false` |
58| `serverAuth()` | Get Better Auth instance in server routes |
59
60## Quick Reference
61
62```ts
63// Client: useUserSession()
64const { user, loggedIn, signIn, signOut } = useUserSession()
65await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })
66```
67
68```ts
69// Server: requireUserSession()
70const { user } = await requireUserSession(event, { user: { role: 'admin' } })
71```
72
73```ts
74// nuxt.config.ts: Route protection
75routeRules: {
76 '/admin/**': { auth: { user: { role: 'admin' } } },
77 '/login': { auth: 'guest' },
78 '/app/**': { auth: 'user' }
79}
80```
81
82## Resources
83
84- [Module Docs](https://github.com/onmax/nuxt-better-auth)
85- [Better Auth Docs](https://www.better-auth.com/)
86
87---
88
89_Token efficiency: Main skill ~300 tokens, each sub-file ~800-1200 tokens_
majiayu000