Nuxt Better Auth

---
name: nuxt-better-auth
description: "Use when implementing auth in Nuxt apps with @nuxtjs/better-auth - provides useUserSession composable, server auth helpers, route protection, and Better Auth plugins integration."
license: MIT
---
<!-- 🔒 LOCKED — managed by clade · auto-generated by sync-to-cursor; edit source in .claude/ then re-run sync -->

# Nuxt Better Auth

Authentication module for Nuxt 4+ built on [Better Auth](https://www.better-auth.com/). Provides composables, server utilities, and route protection.

> **Package rename**: this module moved to the official `nuxt-modules` org.
> The package is `@nuxtjs/better-auth` (>=0.1.4); the old `@onmax/nuxt-better-auth`
> is frozen at 0.1.2. Docs: https://better-auth.nuxt.dev
>
> `better-auth` itself is a hard peer at `>=1.7.1 <2`.

## When to Use

- Installing/configuring `@nuxtjs/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](references/installation.md)**         | Module setup, env vars, config files                                   |
| **[references/client-auth.md](references/client-auth.md)**           | useUserSession, signIn/signUp/signOut, BetterAuthState, safe redirects |
| **[references/server-auth.md](references/server-auth.md)**           | serverAuth, getUserSession, requireUserSession                         |
| **[references/route-protection.md](references/route-protection.md)** | routeRules, definePageMeta, middleware                                 |
| **[references/plugins.md](references/plugins.md)**                   | Better Auth plugins (admin, passkey, 2FA)                              |
| **[references/database.md](references/database.md)**                 | NuxtHub integration, Drizzle schema, custom tables with FKs            |
| **[references/client-only.md](references/client-only.md)**           | External auth backend, clientOnly mode, CORS                           |
| **[references/types.md](references/types.md)**                       | AuthUser, AuthSession, type augmentation                               |

## Loading Files

**Consider loading these reference files based on your task:**

- [ ] [references/installation.md](references/installation.md) - if installing or configuring the module
- [ ] [references/client-auth.md](references/client-auth.md) - if building login/signup/signout flows
- [ ] [references/server-auth.md](references/server-auth.md) - if protecting API routes or accessing user session server-side
- [ ] [references/route-protection.md](references/route-protection.md) - if using routeRules or definePageMeta for auth
- [ ] [references/plugins.md](references/plugins.md) - if integrating Better Auth plugins (admin, passkey, 2FA)
- [ ] [references/database.md](references/database.md) - if setting up database with NuxtHub or Drizzle
- [ ] [references/client-only.md](references/client-only.md) - if using external auth backend with clientOnly mode
- [ ] [references/types.md](references/types.md) - if working with AuthUser, AuthSession, or type augmentation

**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, ready, signOut      |
| `useSignIn(method)`    | Sign-in action handle - execute / status / data / error         |
| `useSignUp(method)`    | Sign-up action handle - 同上                                     |
| `useAuthClient()`      | 取 Better Auth client（可能是 null）                             |
| `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

```ts
// Client: session state
const { user, loggedIn, signOut } = useUserSession()

// Client: sign in（0.1.x 起是獨立 action handle，execute() NEVER throw）
const signIn = useSignIn('email')
await signIn.execute({ email, password })
if (!signIn.error.value) await navigateTo('/')
```

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

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

## Resources

- [Module Docs](https://better-auth.nuxt.dev)
- [Better Auth Docs](https://www.better-auth.com/)

---

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