Production Deployment

Use this guide when your auth flow works locally and you are preparing to ship it to a real environment.

Environment Variables

Production requires a singular or versioned auth secret at runtime:

# Required: 32+ character secret for session encryption
NUXT_BETTER_AUTH_SECRET="your-32-character-secret-here-minimum"

# Alternative for non-destructive rotation
# BETTER_AUTH_SECRETS="2:current-secret-must-be-at-least-32-characters,1:previous-secret-must-be-at-least-32-characters"

# Optional: Auto-detected on Vercel/Cloudflare/Netlify
NUXT_PUBLIC_SITE_URL="https://your-app.com"

# OAuth provider credentials (if using)
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."

Generate a Secure Secret

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Singular secrets must be at least 32 characters. Shorter NUXT_BETTER_AUTH_SECRET or BETTER_AUTH_SECRET values cause auth initialization to throw at runtime. Better Auth validates versioned BETTER_AUTH_SECRETS/secrets entries and warns when the current key is too short.

Security Checklist

Before Deploying

• NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, BETTER_AUTH_SECRETS, or defineServerAuth({ secrets }) is configured
• NUXT_PUBLIC_SITE_URL set (or using Vercel/Cloudflare/Netlify auto-detection)
• trustedOrigins includes every active frontend origin (primary domain and preview domain, if used)
• OAuth redirect URIs configured for production domain
• NODE_ENV=production is set (disables devtools)

Route Protection

Route rules and definePageMeta are for UX (redirects). Always protect API endpoints with requireUserSession:

export default defineEventHandler(async (event) => {
  const { user } = await requireUserSession(event)
  return { data: 'protected' }
})

Rate Limiting

The module does not include built-in rate limiting. Implement rate limiting at the infrastructure level or use a middleware:

import { getRequestIP } from 'h3'

const requests = new Map<string, number[]>()
const WINDOW_MS = 60_000 // 1 minute
const MAX_REQUESTS = 100

export default defineEventHandler((event) => {
  if (!event.path.startsWith('/api/auth'))
    return

  const ip = getRequestIP(event) || 'unknown'
  const now = Date.now()
  const windowStart = now - WINDOW_MS

  const timestamps = (requests.get(ip) || []).filter(t => t > windowStart)
  timestamps.push(now)
  requests.set(ip, timestamps)

  if (timestamps.length > MAX_REQUESTS) {
    throw createError({ statusCode: 429, message: 'Too many requests' })
  }
})

For production, consider using Cloudflare rate limiting or a Redis-backed solution.

Separate Build and Runtime Environments

Some platforms, including Cloudflare Workers Builds, expose build-time and runtime environment variables separately. Your singular or versioned auth secret must be available to the deployed runtime, but it does not need to be present in the build container.

Trusted Origins for Preview Environments

If your workflow uses preview URLs (for example, *.workers.dev), include those origins in your Better Auth server config.

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

export default defineServerAuth({
  trustedOrigins: [
    'https://your-app.com',
    'https://your-preview.workers.dev',
  ],
})

Without the preview origin, browser auth flows can fail because Better Auth rejects cookie-based requests from unknown origins.

NuxtHub Deployment

When deploying with NuxtHub:

1. Database migrations run automatically during build
2. Set environment variables in your deployment platform
3. Ensure @nuxthub/core is listed before @nuxtjs/better-auth in modules

export default defineNuxtConfig({
  modules: [
    '@nuxthub/core',  // Must be first
    '@nuxtjs/better-auth',
  ],
})

Common Issues

"Singular auth secret must be at least 32 characters"

Your NUXT_BETTER_AUTH_SECRET or BETTER_AUTH_SECRET is too short. Generate a new one using the command above. This error is raised when auth initializes at runtime. NUXT_BETTER_AUTH_SECRET remains the recommended variable.

"An auth secret is required in production"

The deployed server runtime could not resolve an auth secret. Set NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, BETTER_AUTH_SECRETS, or secrets in defineServerAuth.

"siteUrl required in production"

The module auto-detects URLs on Vercel, Cloudflare Pages, and Netlify. For other platforms, set NUXT_PUBLIC_SITE_URL to your production domain.

OAuth Redirects Fail

Ensure your OAuth provider's authorized redirect URIs include:

• https://your-app.com/api/auth/callback/google
• https://your-app.com/api/auth/callback/github
• (Replace with your domain and providers)

DevTools

DevTools are automatically disabled in production (NODE_ENV=production). The /api/_better-auth/* endpoints and /__better-auth-devtools page are not registered.