nuxt-better-auth_skill

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