Getting Started
Installation
Learn how to add Nuxt Better Auth to your Nuxt project.
Prompt
Install @onmax/nuxt-better-auth in my Nuxt 4 app.
- Run `npx nuxi module add @onmax/nuxt-better-auth@alpha`
- Set `BETTER_AUTH_SECRET` in `.env` (at least 32 chars, high entropy). Optionally prefix with `NUXT_` for runtime config
- Optionally set `NUXT_PUBLIC_SITE_URL` for non-auto-detected platforms
- Create `server/auth.config.ts` using `defineServerAuth` from `@onmax/nuxt-better-auth/config`
- Create `app/auth.config.ts` using `defineClientAuth` from `@onmax/nuxt-better-auth/config`
- The module auto-injects `secret` and `baseURL` — do not configure them manually
Read more: https://better-auth.nuxt.dev/raw/getting-started/installation.md
Source: https://github.com/nuxt-modules/better-auth
Prerequisites
- Nuxt v4.0+
Add to project
Install the module
npx nuxi module add @onmax/nuxt-better-auth@alpha
Set Environment Variables
When you install the module with
nuxi module add, it prompts you to generate NUXT_BETTER_AUTH_SECRET and can append it to your .env. BETTER_AUTH_SECRET still works as a compatibility fallback. In CI/test environments it auto-generates the secret.Add these environment variables to .env:
- Secret Key
The secret encrypts and hashes sensitive data. Must be at least 32 characters with high entropy.
.env
NUXT_BETTER_AUTH_SECRET=
Or generate via terminal:
openssl rand -base64 32
Use
NUXT_BETTER_AUTH_SECRET for Nuxt runtime config and multi-environment deployments. BETTER_AUTH_SECRET remains supported as a fallback.- Base URL (Optional)
The module auto-detects the URL on Vercel, Cloudflare Pages, and Netlify. Set manually for other platforms.
.env
NUXT_PUBLIC_SITE_URL=https://your-domain.com
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:
- Server Configuration:
server/auth.config.ts - 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 '@onmax/nuxt-better-auth/config'
export default defineServerAuth({
emailAndPassword: { enabled: true }
})
app/auth.config.ts
import { defineClientAuth } from '@onmax/nuxt-better-auth/config'
export default defineClientAuth({})
Need database persistence? See NuxtHub Integration for auto-generated schemas and full database support.