Getting Started

Configuration

Configure the module options and your Better Auth server instance.

Module Configuration

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@onmax/nuxt-better-auth'],
  auth: {
    redirects: {
      login: '/login',
      guest: '/'
    },
  }
})

clientOnly

boolean

Default: falseEnable client-only mode for external auth backends. When true:

Skips server/auth.config.ts requirement
Skips server-side setup (API handlers, middleware, schema generation, devtools)
Skips secret validation

Use this when your Better Auth server runs on a separate backend (e.g., standalone h3/Nitro project).See External Auth Backend guide.

serverConfig

string

Default: 'server/auth.config'Path to the server auth config file, relative to the project root.

clientConfig

string

Default: 'app/auth.config'Path to the client auth config file, relative to the project root.

redirects

{ login?: string, guest?: string }

Default: { login: '/login', guest: '/' }Paths to redirect to when auth protection is triggered.

login: Where to redirect unauthenticated users.
guest: Where to redirect authenticated users trying to access guest-only pages.

secondaryStorage

boolean

Default: falseEnable KV as secondary storage for sessions. This significantly improves performance by reducing database hits for session validation.Requirement: Requires NuxtHub Integration with hub: { kv: true }.

schema.usePlural

boolean

Default: falsePluralize table names (user → users)

schema.casing

'camelCase' | 'snake_case'

Default: camelCaseColumn/table name casing. Falls back to hub.db.casing when not specified.

Server Configuration

Define your authentication logic in server/auth.config.ts, including plugins, providers, and settings.

defineServerAuth

Use the defineServerAuth helper to ensure type safety and access context. It accepts an object or function syntax.

server/auth.config.ts

import { defineServerAuth } from '@onmax/nuxt-better-auth/config'

// Object syntax (simplest)
export default defineServerAuth({
  emailAndPassword: { enabled: true }
})

// Function syntax (access context)
export default defineServerAuth((ctx) => ({
  emailAndPassword: { enabled: true }
}))

The module automatically injects secret and baseURL. You don't need to configure these in defineServerAuth.

Secret: Priority: nuxt.config.ts runtimeConfig > NUXT_BETTER_AUTH_SECRET > BETTER_AUTH_SECRET
Base URL: The module auto-detects the base URL on Vercel/Cloudflare/Netlify. For other platforms, set NUXT_PUBLIC_SITE_URL

Context Options

When using the function syntax, defineServerAuth callback receives a context object with useful properties:

server/auth.config.ts

import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
import { drizzleAdapter } from 'better-auth/adapters/drizzle'

export default defineServerAuth(({ db, runtimeConfig }) => ({
  // Access the database connection (when using NuxtHub)
  database: drizzleAdapter(db),

  // Access runtime config if needed
  // someValue: runtimeConfig.customKey,
}))

Base URL Configuration

The module resolves siteUrl using this priority:

Priority	Source	When Used
1	`NUXT_PUBLIC_SITE_URL`	Explicit config (always wins)
2	Request URL	Auto-detected from HTTP request
3	`VERCEL_URL`, `CF_PAGES_URL`, `URL`	Platform env vars (Vercel, Cloudflare, Netlify)
4	`http://localhost:3000`	Development only

Custom domains or self-hosted: Always set NUXT_PUBLIC_SITE_URL when using custom domains or deploying to your own VPS/server. Platform env vars return auto-generated URLs, not your custom domain.

.env

NUXT_PUBLIC_SITE_URL="https://your-domain.com"

For most deployments, the module auto-detects the request URL correctly. Only set NUXT_PUBLIC_SITE_URL for custom domains or non-request contexts like seed scripts.

Runtime Config

Configure secrets using environment variables (see Installation).

.env

BETTER_AUTH_SECRET="your-super-secret-key"
NUXT_PUBLIC_SITE_URL="https://your-domain.com" # Optional on Vercel/Cloudflare/Netlify

Prefix the variable with NUXT_ to use Nuxt's runtime config system (recommended for multi-environment deployments): NUXT_BETTER_AUTH_SECRET=

For Module Authors

Other Nuxt modules can extend the authentication configuration:

// In your Nuxt module
export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.hook('better-auth:config:extend', (config) => {
      config.plugins = [...(config.plugins || []), myPlugin()]
    })
  }
})

Access sessions from server handlers:

const { user, session } = await getUserSession(event)
if (!user) throw createError({ statusCode: 401 })

Next, set up the Client Configuration.