Registry / auth-security / nuxt-better-auth-utils

nuxt-better-auth-utils

JSON →
library0.1.27jsnpmunverified

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.

npm install nuxt-better-auth-utils
INSTALL
IMPORT
SIG · NUXT-BETTER-AUTH-U
N
nuxt-better-auth-utils
auth-securityjavascriptv0.1.27
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineNuxtConfig
import { defineNuxtConfig } from 'nuxt/config'
const defineNuxtConfig = require('nuxt/config')
Standard Nuxt configuration helper. Always use ESM import in Nuxt 3 projects.
useAuth
const { session, user, loggedIn } = useAuth()
import { useAuth } from '#nuxt-better-auth-utils'
This composable is auto-imported by Nuxt. Explicit import is not typically needed and might lead to issues.
useServerAuth
const { requireSession, getSession } = useServerAuth(event)
import { useServerAuth } from '#nuxt-better-auth-utils'
This utility is auto-imported in server routes/APIs. Explicit import is not typically needed.
defineAuthConfig
import { defineAuthConfig } from '#nuxt-better-auth-utils/server'
import { defineAuthConfig } from 'better-auth'
Used in `server/auth.server.config.ts`. The module provides a specific alias for this.
defineAuthClientConfig
import { defineAuthClientConfig } from '#nuxt-better-auth-utils/client'
import { defineAuthClientConfig } from 'better-auth/client'
Used in `app/auth.client.config.ts`. The module provides a specific alias for this.

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>
Debug
Known issues
gotchaThe 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.
affects: >=0.1.0
breakingFixes 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.
affects: >=0.1.25
gotchaUsing `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`.
affects: >=0.1.0
gotchaThe `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.
affects: >=0.1.0
gotchaWhen 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.
affects: 0.1.0 - 0.1.20
Errors
Common errors & fixes
Cannot find name 'useAuth'. Did you mean 'Auth'?
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`.
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
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.
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.
Upgrade
Version history
0.1.27latest on npm
Audit
Dependencies
better-authrequiredCore authentication library, peer dependency.
Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
nuxt-better-auth-utils — npm install nuxt-better-auth-utils · libregistry