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.19) 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
- Adding i18n support with
@nuxtjs/i18n
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 |
Loading Files
Consider loading these reference files based on your task:
DO NOT load all files at once. Load only what's relevant to your current 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
// 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.19) 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- Using clientOnly mode for external auth backends
22- Adding i18n support with `@nuxtjs/i18n`
23
24**For Nuxt patterns:** use `nuxt` skill
25**For NuxtHub database:** use `nuxthub` skill
26
27## Available Guidance
28
29| File | Topics |
30| -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
31| **[references/installation.md](references/installation.md)** | Module setup, env vars, config files |
32| **[references/client-auth.md](references/client-auth.md)** | useUserSession, signIn/signUp/signOut, BetterAuthState, safe redirects |
33| **[references/server-auth.md](references/server-auth.md)** | serverAuth, getUserSession, requireUserSession |
34| **[references/route-protection.md](references/route-protection.md)** | routeRules, definePageMeta, middleware |
35| **[references/plugins.md](references/plugins.md)** | Better Auth plugins (admin, passkey, 2FA) |
36| **[references/database.md](references/database.md)** | NuxtHub integration, Drizzle schema, custom tables with FKs |
37| **[references/client-only.md](references/client-only.md)** | External auth backend, clientOnly mode, CORS |
38| **[references/types.md](references/types.md)** | AuthUser, AuthSession, type augmentation |
39
40## Loading Files
41
42**Consider loading these reference files based on your task:**
43
44- [ ] [references/installation.md](references/installation.md) - if installing or configuring the module
45- [ ] [references/client-auth.md](references/client-auth.md) - if building login/signup/signout flows
46- [ ] [references/server-auth.md](references/server-auth.md) - if protecting API routes or accessing user session server-side
47- [ ] [references/route-protection.md](references/route-protection.md) - if using routeRules or definePageMeta for auth
48- [ ] [references/plugins.md](references/plugins.md) - if integrating Better Auth plugins (admin, passkey, 2FA)
49- [ ] [references/database.md](references/database.md) - if setting up database with NuxtHub or Drizzle
50- [ ] [references/client-only.md](references/client-only.md) - if using external auth backend with clientOnly mode
51- [ ] [references/types.md](references/types.md) - if working with AuthUser, AuthSession, or type augmentation
52
53**DO NOT load all files at once.** Load only what's relevant to your current task.
54
55## Key Concepts
56
57| Concept | Description |
58| ---------------------- | --------------------------------------------------------------- |
59| `useUserSession()` | Client composable - user, session, loggedIn, signIn/Out methods |
60| `requireUserSession()` | Server helper - throws 401/403 if not authenticated |
61| `auth` route mode | `'user'`, `'guest'`, `{ user: {...} }`, or `false` |
62| `serverAuth()` | Get Better Auth instance in server routes |
63
64## Quick Reference
65
66```ts
67// Client: useUserSession()
68const { user, loggedIn, signIn, signOut } = useUserSession()
69await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })
70```
71
72```ts
73// Server: requireUserSession()
74const { user } = await requireUserSession(event, { user: { role: 'admin' } })
75```
76
77```ts
78// nuxt.config.ts: Route protection
79routeRules: {
80 '/admin/**': { auth: { user: { role: 'admin' } } },
81 '/login': { auth: 'guest' },
82 '/app/**': { auth: 'user' }
83}
84```
85
86## Resources
87
88- [Module Docs](https://github.com/onmax/nuxt-better-auth)
89- [Better Auth Docs](https://www.better-auth.com/)
90
91---
92
93_Token efficiency: Main skill ~300 tokens, each sub-file ~800-1200 tokens_
aibot88