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 NUXT_BETTER_AUTH_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. Inherits from hub.db.casing if not set.

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.

server/auth.config.ts

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

export default defineServerAuth(() => {
  return {
    emailAndPassword: {
      enabled: true
    }
  }
})

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

Secret: Reads from NUXT_BETTER_AUTH_SECRET or BETTER_AUTH_SECRET
Base URL: Auto-detected on Vercel/Cloudflare/Netlify, or set NUXT_PUBLIC_SITE_URL

Context Options

The defineServerAuth callback receives a context object with useful properties:

server/auth.config.ts

import { defineServerAuth } from '@onmax/nuxt-better-auth'
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 request URL is auto-detected correctly. Only set NUXT_PUBLIC_SITE_URL for custom domains or non-request contexts like seed scripts.

Runtime Config

Configure secrets via environment variables (see Installation).

.env

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

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.