Nuxt Better Auth Utilities

Common errors

• Cannot find name 'useAuth'. Did you mean 'Auth'?

  cause Nuxt auto-imports are not correctly registered or processed.
  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.

• Error: [nuxt] `betterAuthUtils` module options are not defined in `nuxt.config.ts`.

  cause The module itself is not added to the `modules` array in `nuxt.config.ts`.
  fix Add `'nuxt-better-auth-utils'` to the `modules` array in your `nuxt.config.ts`.

• TypeError: Cannot read properties of undefined (reading 'user') in useServerAuth

  cause Attempting to access `session.user` when `session` is `null` because the user is unauthenticated, and `getSession` was used instead of `requireSession`.
  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)`.

• Error: 'BETTER_AUTH_SECRET' environment variable is not set.

  cause The mandatory secret environment variable is missing.
  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.

Warnings

• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha Using `useServerAuth()` requires an `event` object in server routes. For example, `const session = await requireSession(event)`.
  Fix: Always pass the `event` object received by `defineEventHandler` to `useServerAuth()` methods like `requireSession` or `getSession`.
• gotcha The `BETTER_AUTH_SECRET` environment variable (or `NUXT_SECRET`) is mandatory for the module to function correctly, ensuring secure session handling.
  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.
• gotcha 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.
  Fix: Upgrade to `v0.1.21` or newer. This version uses `$Infer.Session` for server auth types to mitigate the depth limit issue.

Install

• npm install nuxt-better-auth-utils npm
• yarn add nuxt-better-auth-utils yarn
• pnpm add nuxt-better-auth-utils pnpm

Imports

• defineNuxtConfig
  wrong:

  const defineNuxtConfig = require('nuxt/config')

  correct:

  import { defineNuxtConfig } from 'nuxt/config'

  Standard Nuxt configuration helper. Always use ESM import in Nuxt 3 projects.
• useAuth
  wrong:

  import { useAuth } from '#nuxt-better-auth-utils'

  correct:

  const { session, user, loggedIn } = useAuth()

  This composable is auto-imported by Nuxt. Explicit import is not typically needed and might lead to issues.
• useServerAuth
  wrong:

  import { useServerAuth } from '#nuxt-better-auth-utils'

  correct:

  const { requireSession, getSession } = useServerAuth(event)

  This utility is auto-imported in server routes/APIs. Explicit import is not typically needed.
• defineAuthConfig
  wrong:

  import { defineAuthConfig } from 'better-auth'

  correct:

  import { defineAuthConfig } from '#nuxt-better-auth-utils/server'

  Used in `server/auth.server.config.ts`. The module provides a specific alias for this.
• defineAuthClientConfig
  wrong:

  import { defineAuthClientConfig } from 'better-auth/client'

  correct:

  import { defineAuthClientConfig } from '#nuxt-better-auth-utils/client'

  Used in `app/auth.client.config.ts`. The module provides a specific alias for this.

Quickstart

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.

import { drizzleAdapter } from 'better-auth/adapters/drizzle';
import { organization } from 'better-auth/plugins';
import { defineDrizzleConfig, useDrizzle } from '#nuxt-drizzle'; // Assuming nuxt-drizzle for DB

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    'nuxt-better-auth-utils',
    '#some-database-module' // e.g., 'nuxt-drizzle'
  ],
  betterAuthUtils: {
    redirectTo: '/login',
  },
  // Configure other modules like nuxt-drizzle if used
  // drizzle: { ... }
});

// server/auth.server.config.ts
// Ensure database client is available via your preferred Nuxt database module.
// This example assumes `useDrizzle()` from `nuxt-drizzle`.
export default defineAuthConfig(() => {
  // In a real application, replace useDrizzle with your actual database client setup
  const db = useDrizzle(); // Example using a hypothetical nuxt-drizzle hook
  return {
    database: drizzleAdapter(db, { provider: 'pg' }), // Replace with your adapter
    emailAndPassword: { enabled: true },
    plugins: [organization()],
  };
});

// app/auth.client.config.ts
import { organizationClient } from 'better-auth/client/plugins';
export default defineAuthClientConfig({
  plugins: [organizationClient()],
});

// pages/protected.vue
<script setup lang="ts">
definePageMeta({
  middleware: 'auth',
});
const { session, user, loggedIn, signOut } = useAuth();
</script>

<template>
  <div>
    <h1>Welcome, {{ user?.email }}!</h1>
    <p v-if="loggedIn">You are logged in.</p>
    <button @click="signOut({ redirectTo: '/login' })">Sign Out</button>
  </div>
</template>