Getting Started

Installation

Learn how to add Nuxt Better Auth to your Nuxt project.
Prompt
Install @nuxtjs/better-auth in my Nuxt app.

- Read the raw installation documentation first: https://better-auth.nuxt.dev/raw/getting-started/installation.md
- Run `npx nuxi module add @nuxtjs/better-auth`
- Set `NUXT_APP_SECRET` in `.env` on Nuxt 4.6+, or `NUXT_BETTER_AUTH_SECRET` or `BETTER_AUTH_SECRETS` on any version (at least 32 chars per current secret, high entropy). A configured auth secret takes precedence over `NUXT_APP_SECRET`
- Set `NUXT_PUBLIC_SITE_URL` for Cloudflare Workers, custom domains, and production hosts without a supported platform URL variable
- Create `server/auth.config.ts` using `defineServerAuth` from `@nuxtjs/better-auth/config`
- Create `app/auth.config.ts` using `defineClientAuth` from `@nuxtjs/better-auth/config`
- The module auto-injects `secret` and `baseURL` — do not configure them manually
- In `defineServerAuth`, use the app config callback's `requestOrigin` when Better Auth needs the current request host, such as `trustedOrigins`

Use this page when you want the full install checklist rather than the shorter quickstart.

Prerequisites

  • Nuxt 4.0 or newer. On Nuxt 4.6 and newer, the module's server code is built on nuxt/server when the app runs Nitro v3 or a server.builder other than Nitro. Apps on nitropack v2 keep the h3 v1 runtime.
  • Node.js ^22.19.0, ^24.11.0, or >=26.0.0
  • A Better Auth 1.x version that satisfies this package's peer dependency range
  • NuxtHub 0.10.5 or newer if you plan to use the optional NuxtHub integration
  • a package manager configured for your app
  • a local .env file or deployment environment variable system

Add to project

Install the module

npx nuxi module add @nuxtjs/better-auth

Set environment variables

When you install the module with nuxi module add, it prompts you to generate a secret and can append it to your .env: NUXT_APP_SECRET on Nuxt 4.6+, NUXT_BETTER_AUTH_SECRET on older versions. The prompt is skipped when NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, or BETTER_AUTH_SECRETS is already configured, or on Nuxt 4.6+ when NUXT_APP_SECRET is. In CI/test environments it generates the secret without asking.

Add these environment variables to .env:

  1. Secret Key

The secret encrypts and hashes sensitive data. Must be at least 32 characters with high entropy.

On Nuxt 4.6 and newer, set Nuxt's application secret. When no auth secret is configured, the module derives one from it with deriveSecret('better-auth:secret'):

.env
NUXT_APP_SECRET=

In development, Nuxt generates an appSecret when you have not set one. The module does not derive its secret from that generated value: it keeps Better Auth's development default, so existing development sessions stay valid until you set NUXT_APP_SECRET.

On older Nuxt versions, or to keep a dedicated auth secret, set NUXT_BETTER_AUTH_SECRET instead:

.env
NUXT_BETTER_AUTH_SECRET=

Or generate via terminal:

openssl rand -base64 32
NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, BETTER_AUTH_SECRETS, and secrets in defineServerAuth always take precedence over NUXT_APP_SECRET, so existing apps keep their sessions. Removing them from a deployment changes the auth secret: users are signed out and data encrypted with the old secret can no longer be read.

For non-destructive rotation, use Better Auth's versioned environment variable instead:

.env
BETTER_AUTH_SECRETS=2:current-secret-must-be-at-least-32-characters,1:previous-secret-must-be-at-least-32-characters
  1. Base URL

Set NUXT_PUBLIC_SITE_URL for Cloudflare Workers, custom domains, and production hosts without a supported platform URL variable. For platform domains, the module can use VERCEL_URL (Vercel), CF_PAGES_URL (Cloudflare Pages), or URL (Netlify) when available at runtime.

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

Cloudflare Workers does not supply CF_PAGES_URL. Configure NUXT_PUBLIC_SITE_URL in the Worker's runtime variables, including for workers.dev deployments. Without an explicit or supported platform URL, production auth initialization fails.

Create configuration files

During module install, server/auth.config.ts and <srcDir>/auth.config.ts are scaffolded if missing. The client config is placed in your srcDir (e.g., app/ or project root).

The module requires two configuration files:

  1. Server Configuration: server/auth.config.ts
  2. Client Configuration: <srcDir>/auth.config.ts (e.g., app/auth.config.ts)

Create these files with the following content:

server/auth.config.ts
import { defineServerAuth } from '@nuxtjs/better-auth/config'

export default defineServerAuth({
  emailAndPassword: { enabled: true }
})
app/auth.config.ts
import { defineClientAuth } from '@nuxtjs/better-auth/config'

export default defineClientAuth({})

Verify the installation

Confirm all of the following:

  • Nuxt starts without missing-config errors
  • server/auth.config.ts exists
  • app/auth.config.ts or your srcDir equivalent exists
  • a singular or versioned auth secret is available at runtime

Next steps

Need database persistence? See NuxtHub Integration for auto-generated schemas and full database support.
Bring your own database? Use Drizzle, Prisma, or Kysely adapters with any database.
Edit on GitHub
Previous

Introduction

Next

Configuration