playbooks

home / skills / onmax / nuxt-skills / nuxt-better-auth

nuxt-better-auth skill

/skills/nuxt-better-auth

This skill helps you implement authentication in Nuxt 4+ using Better Auth, providing useUserSession, server helpers, and route protection.

npx playbooks add skill onmax/nuxt-skills --skill nuxt-better-auth

Review the files below or copy the command above to add this skill to your agents.

Files (9)
SKILL.md
4.4 KB
---
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](https://www.better-auth.com/). 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](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                               |

## Usage Pattern

**Load based on context:**

- Installing module? → [references/installation.md](references/installation.md)
- Login/signup forms? → [references/client-auth.md](references/client-auth.md)
- API route protection? → [references/server-auth.md](references/server-auth.md)
- Route rules/page meta? → [references/route-protection.md](references/route-protection.md)
- Using plugins? → [references/plugins.md](references/plugins.md)
- Database setup? → [references/database.md](references/database.md)
- External auth backend? → [references/client-only.md](references/client-only.md)
- TypeScript types? → [references/types.md](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

```ts
// Client: useUserSession()
const { user, loggedIn, signIn, signOut } = useUserSession()
await signIn.email({ email, password }, { onSuccess: () => 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://github.com/onmax/nuxt-better-auth)
- [Better Auth Docs](https://www.better-auth.com/)

---

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

Overview

This skill integrates @onmax/nuxt-better-auth into Nuxt 4+ apps to provide a complete auth surface for client and server code. It supplies the useUserSession composable, server helpers (serverAuth, requireUserSession, getUserSession), route protection via routeRules and page meta, and plugin integration for Better Auth features. It is alpha software; expect API changes and avoid production use without validation.

How this skill works

The skill exposes a client composable (useUserSession) that returns user, session, loggedIn state and signIn/signOut helpers. On the server it supplies serverAuth and requireUserSession to read or enforce sessions inside API endpoints and middleware. Route protection works by configuring routeRules or definePageMeta with auth modes (user, guest, role-constraints) and the module wires Better Auth plugins and NuxtHub database integration when configured.

When to use it

  • Setting up @onmax/nuxt-better-auth in a Nuxt 4+ project
  • Implementing login, signup, signout and client session flows
  • Protecting server API routes and pages with role-based rules
  • Accessing user session inside server handlers or middleware
  • Integrating Better Auth plugins (admin panel, passkeys, 2FA) or NuxtHub database

Best practices

  • Use useUserSession on pages/components for reactive session state and safe redirects after sign-in/out
  • Enforce server-side checks with requireUserSession for protected API routes to avoid client-side bypasses
  • Declare routeRules in nuxt.config or use definePageMeta for per-page auth to centralize access control
  • Use clientOnly mode for external auth backends and configure CORS and callbacks explicitly
  • Keep auth-related types (AuthUser, AuthSession) in your TypeScript types file to ensure consistent shape across client and server

Example use cases

  • Protect an admin area: routeRules '/admin/**' -> auth: { user: { role: 'admin' } } and requireUserSession in server endpoints
  • Standard login flow: useUserSession.signIn.email(...) then navigateTo('/') on success
  • API route that returns user data: call const { user } = await requireUserSession(event) inside the server handler
  • Enable passkeys or 2FA plugin via the module plugins config to add extra authentication methods
  • Use NuxtHub integration to store users and sessions with Drizzle schemas for relational data

FAQ

Is this safe for production?

This module is currently alpha. Test thoroughly and expect breaking API changes before a stable release.

How do I protect an API route?

Call requireUserSession(event, { user: {...} }) inside the server handler to enforce authentication and optional role checks.