A Nuxt module for simple, flexible authentication in your Nuxt applications.
- ⚙️  Auto-scanning of client and server configs for end-to-end TS support
- 🚀  Built-in authentication middleware
- 🔑  Multiple authentication strategies (username, email, ...)
- 🛡️  Role-based access control
- 🔄  Session management
- đź”’ Â Redirect handling for authenticated/unauthenticated users
- Install the module:
# Using npm npm install better-auth-nuxt better-auth # Using yarn yarn add better-auth-nuxt better-auth # Using pnpm pnpm add better-auth-nuxt better-auth- Add the module to your
nuxt.config.ts:
export default defineNuxtConfig({ modules: ['better-auth-nuxt'], betterAuth: { // Configure auth endpoints (default: '/api/auth/**') endpoint: '/api/auth/**', // Configure redirect paths redirectOptions: { redirectGuestTo: '/auth/login', redirectUserTo: '/', redirectUnauthorizedTo: '/401', }, // Configure client and server options options: { client: { basePath: '/api/auth', // Optional: baseURL, disableDefaultFetchPlugins }, server: { appName: 'My Nuxt App', // Optional: baseURL, basePath, secret }, }, } })- Use the module in your pages:
<script setup> // Protect route for authenticated users only definePageMeta({ auth: { only: 'user', } }) // Access auth functionality const { loggedIn, user, signOut } = useUserSession() </script> <template> <div v-if="loggedIn"> <h1>Welcome, {{ user?.name }}</h1> <button @click="signOut()">Sign Out</button> </div> </template>interface ModuleOptions { // Auth endpoint endpoint: string // Patterns to match auth configuration files serverConfigs?: string[] clientConfigs?: string[] // Client and server options options: { client?: ModuleClientOptions server?: ModuleServerOptions } // Redirect options redirectOptions: { redirectUserTo?: string redirectGuestTo?: string redirectUnauthorizedTo?: string } }interface ModuleServerOptions { appName?: string // Application name baseURL?: string // Base URL for the auth API basePath?: string // Base path for the auth API secret?: string // Secret for JWT/session encryption }interface ModuleClientOptions { baseURL?: string // Base URL for the auth API basePath?: string // Base path for the auth API disableDefaultFetchPlugins?: boolean // Disable default fetch plugins }Provides access to the authenticated user session and auth methods.
const { // State loggedIn, // Ref<boolean> - Is the user logged in user, // Ref<User> - Current user data session, // Ref<Session> - Current session data // Methods fetchSession, // () => Promise<void> - Fetch current session signIn: { username, // (credentials) => Promise<void> - Sign in with username email, // (credentials) => Promise<void> - Sign in with email }, signUp: { username, // (userData) => Promise<void> - Register with username email, // (userData) => Promise<void> - Register with email }, signOut, // (options?) => Promise<void> - Sign out the user // Configuration options, // Auth configuration options } = useUserSession()Access the auth instance on the server.
// In API route handlers: const auth = useAuth()Use the auth meta property to protect routes:
definePageMeta({ auth: { // Only allow specific roles only: 'user' | 'admin' | 'guest' | ['user', 'admin'], // Custom redirect paths (override global config) redirectUserTo: '/dashboard', redirectGuestTo: '/login', redirectUnauthorizedTo: '/unauthorized', } })You can create configuration files to customize authentication:
Create a *.better-auth.ts file to configure server-side auth:
// server/my-auth.better-auth.ts import type { BetterAuthOptions } from 'better-auth' export default () => ({ // Custom server-side auth configuration } satisfies BetterAuthOptions)Create a *.better-auth-client.ts file to configure client-side auth:
// app/my-auth.better-auth-client.ts import type { ClientOptions } from 'better-auth' export default { // Custom client-side auth configuration } satisfies ClientOptionsNote: After adding or modifying configuration files, run
pnpm nuxt prepareto ensure your changes are properly recognized by Nuxt.
Local development
# Install dependencies pnpm install # Generate type stubs pnpm dev:prepare # Develop with the playground pnpm dev # Build the playground pnpm dev:build # Run ESLint pnpm lint # Run Vitest pnpm test pnpm test:watch # Release new version pnpm release