{"id":16738,"library":"nuxt-better-auth-utils","title":"Nuxt Better Auth Utilities","description":"nuxt-better-auth-utils is a Nuxt module providing a full lifecycle integration for the Better Auth library, offering auto-wired API handlers, SSR session pre-fetching, and typed server/client APIs. It's currently at version 0.1.27 and has a rapid release cadence with frequent bug fixes and minor improvements, often multiple releases per week. Key differentiators include its tight integration with Nuxt's SSR capabilities, providing reactive session state via `useAuth()` on the client and `useServerAuth()` for server-side operations, and automatic type inference. It remains database-agnostic, deferring to Better Auth's adapter ecosystem. This module aims to simplify authentication setup in Nuxt applications by handling much of the boilerplate, including API routing, session management, and protecting pages with middleware, without imposing opinions on the underlying authentication strategy or data storage.","status":"active","version":"0.1.27","language":"javascript","source_language":"en","source_url":"https://github.com/genu/nuxt-better-auth-utils","tags":["javascript"],"install":[{"cmd":"npm install nuxt-better-auth-utils","lang":"bash","label":"npm"},{"cmd":"yarn add nuxt-better-auth-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add nuxt-better-auth-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication library, peer dependency.","package":"better-auth","optional":false}],"imports":[{"note":"Standard Nuxt configuration helper. Always use ESM import in Nuxt 3 projects.","wrong":"const defineNuxtConfig = require('nuxt/config')","symbol":"defineNuxtConfig","correct":"import { defineNuxtConfig } from 'nuxt/config'"},{"note":"This composable is auto-imported by Nuxt. Explicit import is not typically needed and might lead to issues.","wrong":"import { useAuth } from '#nuxt-better-auth-utils'","symbol":"useAuth","correct":"const { session, user, loggedIn } = useAuth()"},{"note":"This utility is auto-imported in server routes/APIs. Explicit import is not typically needed.","wrong":"import { useServerAuth } from '#nuxt-better-auth-utils'","symbol":"useServerAuth","correct":"const { requireSession, getSession } = useServerAuth(event)"},{"note":"Used in `server/auth.server.config.ts`. The module provides a specific alias for this.","wrong":"import { defineAuthConfig } from 'better-auth'","symbol":"defineAuthConfig","correct":"import { defineAuthConfig } from '#nuxt-better-auth-utils/server'"},{"note":"Used in `app/auth.client.config.ts`. The module provides a specific alias for this.","wrong":"import { defineAuthClientConfig } from 'better-auth/client'","symbol":"defineAuthClientConfig","correct":"import { defineAuthClientConfig } from '#nuxt-better-auth-utils/client'"}],"quickstart":{"code":"import { drizzleAdapter } from 'better-auth/adapters/drizzle';\nimport { organization } from 'better-auth/plugins';\nimport { defineDrizzleConfig, useDrizzle } from '#nuxt-drizzle'; // Assuming nuxt-drizzle for DB\n\n// nuxt.config.ts\nexport default defineNuxtConfig({\n  modules: [\n    'nuxt-better-auth-utils',\n    '#some-database-module' // e.g., 'nuxt-drizzle'\n  ],\n  betterAuthUtils: {\n    redirectTo: '/login',\n  },\n  // Configure other modules like nuxt-drizzle if used\n  // drizzle: { ... }\n});\n\n// server/auth.server.config.ts\n// Ensure database client is available via your preferred Nuxt database module.\n// This example assumes `useDrizzle()` from `nuxt-drizzle`.\nexport default defineAuthConfig(() => {\n  // In a real application, replace useDrizzle with your actual database client setup\n  const db = useDrizzle(); // Example using a hypothetical nuxt-drizzle hook\n  return {\n    database: drizzleAdapter(db, { provider: 'pg' }), // Replace with your adapter\n    emailAndPassword: { enabled: true },\n    plugins: [organization()],\n  };\n});\n\n// app/auth.client.config.ts\nimport { organizationClient } from 'better-auth/client/plugins';\nexport default defineAuthClientConfig({\n  plugins: [organizationClient()],\n});\n\n// pages/protected.vue\n<script setup lang=\"ts\">\ndefinePageMeta({\n  middleware: 'auth',\n});\nconst { session, user, loggedIn, signOut } = useAuth();\n</script>\n\n<template>\n  <div>\n    <h1>Welcome, {{ user?.email }}!</h1>\n    <p v-if=\"loggedIn\">You are logged in.</p>\n    <button @click=\"signOut({ redirectTo: '/login' })\">Sign Out</button>\n  </div>\n</template>","lang":"typescript","description":"This quickstart demonstrates the core setup of nuxt-better-auth-utils, including Nuxt module configuration, defining server and client authentication configurations, and using the `useAuth()` composable and `auth` middleware to protect a page. It illustrates integration with a hypothetical Drizzle database adapter."},"warnings":[{"fix":"Ensure `server/auth.server.config.ts` and `app/auth.client.config.ts` are correctly placed. Use `defineAuthConfig` and `defineAuthClientConfig` imported from the module's virtual aliases.","message":"The module expects a `server/auth.server.config.ts` and `app/auth.client.config.ts` for configuration. These files must be placed in their respective `server/` and `app/` directories for auto-imports and correct module integration.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Update to the latest version of `nuxt-better-auth-utils` and ensure your Nuxt environment is up-to-date. Recheck type definitions and auto-imported functions for any conflicts, especially for custom session types or server utilities.","message":"Fixes in recent versions (0.1.26, 0.1.25) involved refactoring autoimport registration and separating runtime JS and type declarations for Nitro compatibility. Older setups might experience issues with auto-imports or type resolution.","severity":"breaking","affected_versions":">=0.1.25"},{"fix":"Always pass the `event` object received by `defineEventHandler` to `useServerAuth()` methods like `requireSession` or `getSession`.","message":"Using `useServerAuth()` requires an `event` object in server routes. For example, `const session = await requireSession(event)`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set `BETTER_AUTH_SECRET` in your `.env` file (e.g., `BETTER_AUTH_SECRET='super-secret-key-that-is-at-least-32-chars-long'`) or `NUXT_SECRET` for production deployments.","message":"The `BETTER_AUTH_SECRET` environment variable (or `NUXT_SECRET`) is mandatory for the module to function correctly, ensuring secure session handling.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to `v0.1.21` or newer. This version uses `$Infer.Session` for server auth types to mitigate the depth limit issue.","message":"When inferring server auth types from user config, `useServerAuth` might hit TypeScript depth limits if complex session types are used. This was addressed in v0.1.21.","severity":"gotcha","affected_versions":"0.1.0 - 0.1.20"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `nuxt-better-auth-utils` is correctly listed in your `nuxt.config.ts` modules array. Restart your Nuxt development server. Check for any `tsconfig.json` misconfigurations.","cause":"Nuxt auto-imports are not correctly registered or processed.","error":"Cannot find name 'useAuth'. Did you mean 'Auth'?"},{"fix":"Add `'nuxt-better-auth-utils'` to the `modules` array in your `nuxt.config.ts`.","cause":"The module itself is not added to the `modules` array in `nuxt.config.ts`.","error":"Error: [nuxt] `betterAuthUtils` module options are not defined in `nuxt.config.ts`."},{"fix":"Use `requireSession(event)` if an authenticated user is strictly required (it throws an error for unauthenticated requests), or defensively check `if (session) { /* ... */ }` after `getSession(event)`.","cause":"Attempting to access `session.user` when `session` is `null` because the user is unauthenticated, and `getSession` was used instead of `requireSession`.","error":"TypeError: Cannot read properties of undefined (reading 'user') in useServerAuth"},{"fix":"Set `BETTER_AUTH_SECRET` in your `.env` file (e.g., `BETTER_AUTH_SECRET='a-strong-random-secret-at-least-32-chars'`) or provide it through your hosting environment configuration.","cause":"The mandatory secret environment variable is missing.","error":"Error: 'BETTER_AUTH_SECRET' environment variable is not set."}],"ecosystem":"npm"}