fix: consider NUXT_BETTER_AUTH_SECRET for env validation (#271)

jd-solanki · web-flow · commit 776331f7e292 · 2026-03-22T10:11:27.000+01:00
diff --git a/docs/app/components/GenerateSecret.vue b/docs/app/components/GenerateSecret.vue
@@ -21,8 +21,8 @@ function generate() {
   for (const block of codeBlocks) {
     const spans = block.querySelectorAll('span.line span')
     for (const span of spans) {
-      if (span.textContent?.includes('BETTER_AUTH_SECRET=')) {
-        span.textContent = `BETTER_AUTH_SECRET=${secretValue.value}`
+      if (span.textContent?.includes('NUXT_BETTER_AUTH_SECRET=')) {
+        span.textContent = `NUXT_BETTER_AUTH_SECRET=${secretValue.value}`
         // Hide copy button on this code block
         const pre = block.closest('pre')
         const copyBtn = pre?.querySelector('button')
@@ -37,8 +37,8 @@ function generate() {
     for (const block of codeBlocks) {
       const spans = block.querySelectorAll('span.line span')
       for (const span of spans) {
-        if (span.textContent?.includes('BETTER_AUTH_SECRET=')) {
-          span.textContent = 'BETTER_AUTH_SECRET='
+        if (span.textContent?.includes('NUXT_BETTER_AUTH_SECRET=')) {
+          span.textContent = 'NUXT_BETTER_AUTH_SECRET='
           // Restore copy button
           const pre = block.closest('pre')
           const copyBtn = pre?.querySelector('button')
@@ -56,7 +56,7 @@ function generate() {
 
 async function copySecret() {
   if (secretValue.value) {
-    await copy(`BETTER_AUTH_SECRET=${secretValue.value}`)
+    await copy(`NUXT_BETTER_AUTH_SECRET=${secretValue.value}`)
     copied.value = true
     toast.add({ title: 'Copied to clipboard', icon: 'i-lucide-check', color: 'success' })
   }
diff --git a/docs/content/1.getting-started/0.index.md b/docs/content/1.getting-started/0.index.md
@@ -70,7 +70,7 @@ export default defineNuxtConfig({
 ```
 
 ```ini [.env]
-BETTER_AUTH_SECRET="generate-a-32-char-secret"
+NUXT_BETTER_AUTH_SECRET="generate-a-32-char-secret"
 ```
 
 ### Create Config Files
diff --git a/docs/content/1.getting-started/1.installation.md b/docs/content/1.getting-started/1.installation.md
@@ -21,7 +21,7 @@ npx nuxi module add @onmax/nuxt-better-auth@alpha
 ### Set Environment Variables
 
 ::tip{icon="i-lucide-sparkles"}
-When you install the module with `nuxi module add`, it prompts you to generate `BETTER_AUTH_SECRET` and can append it to your `.env`. In CI/test environments it auto-generates the secret.
+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`:
@@ -31,7 +31,7 @@ Add these environment variables to `.env`:
 The secret encrypts and hashes sensitive data. Must be at least 32 characters with high entropy.
 
 ```txt [.env]
-BETTER_AUTH_SECRET=
+NUXT_BETTER_AUTH_SECRET=
 ```
 
 ::generate-secret
@@ -44,7 +44,7 @@ openssl rand -base64 32
 ```
 
 ::tip
-Prefix the variable with `NUXT_` to use Nuxt's runtime config system (recommended for multi-environment deployments): `NUXT_BETTER_AUTH_SECRET=`
+Use `NUXT_BETTER_AUTH_SECRET` for Nuxt runtime config and multi-environment deployments. `BETTER_AUTH_SECRET` remains supported as a fallback.
 ::
 
 2. **Base URL** (Optional)
diff --git a/docs/content/1.getting-started/2.configuration.md b/docs/content/1.getting-started/2.configuration.md
@@ -237,12 +237,12 @@ The module can auto-detect the request URL on most deployments. You should still
 Configure secrets using environment variables (see [Installation](/getting-started/installation#set-environment-variables)).
 
 ```ini [.env]
-BETTER_AUTH_SECRET="your-super-secret-key"
+NUXT_BETTER_AUTH_SECRET="your-super-secret-key"
 NUXT_PUBLIC_SITE_URL="https://your-domain.com" # Optional on Vercel/Cloudflare/Netlify
 ```
 
 ::tip
-Prefix the variable with `NUXT_` to use Nuxt's runtime config system (recommended for multi-environment deployments): `NUXT_BETTER_AUTH_SECRET=`
+Use `NUXT_BETTER_AUTH_SECRET` as the primary secret variable. `BETTER_AUTH_SECRET` remains supported as a fallback for existing setups.
 ::
 
 ## For Module Authors
diff --git a/docs/content/3.guides/4.database-less-mode.md b/docs/content/3.guides/4.database-less-mode.md
@@ -12,7 +12,7 @@ See the official **Better Auth documentation** for database-less setup.
 Database-less mode uses **JWE (JSON Web Encryption)** sessions. Instead of storing sessions in a database, the session data is encrypted and stored entirely in the cookie.
 
 **How it works:**
-- Session data is encrypted with your `BETTER_AUTH_SECRET`
+- Session data is encrypted with your `NUXT_BETTER_AUTH_SECRET` (`BETTER_AUTH_SECRET` is also supported as a fallback)
 - The encrypted token is stored in a cookie
 - On each request, the server decrypts the cookie to get session data
 - No database queries needed for session validation
diff --git a/docs/content/3.guides/9.production-deployment.md b/docs/content/3.guides/9.production-deployment.md
@@ -115,9 +115,9 @@ export default defineNuxtConfig({
 
 ## Common Issues
 
-### "BETTER_AUTH_SECRET must be at least 32 characters"
+### "NUXT_BETTER_AUTH_SECRET must be at least 32 characters"
 
-Your secret is too short. Generate a new one using the command above.
+Your secret is too short. Generate a new one using the command above. `BETTER_AUTH_SECRET` is still accepted as a fallback, but `NUXT_BETTER_AUTH_SECRET` is the recommended variable.
 
 ### "siteUrl required in production"
 
diff --git a/docs/public/.well-known/skills/nuxt-better-auth/references/installation.md b/docs/public/.well-known/skills/nuxt-better-auth/references/installation.md
@@ -34,7 +34,8 @@ export default defineNuxtConfig({
 
 ```bash
 # Required (min 32 chars)
-BETTER_AUTH_SECRET=your-secret-key-at-least-32-characters
+NUXT_BETTER_AUTH_SECRET=your-secret-key-at-least-32-characters
+# Legacy fallback also supported: BETTER_AUTH_SECRET=your-secret-key-at-least-32-characters
 
 # Required in production for OAuth
 NUXT_PUBLIC_SITE_URL=https://your-domain.com
diff --git a/src/module.ts b/src/module.ts
@@ -77,7 +77,7 @@ export default defineNuxtModule<BetterAuthModuleOptions>({
     const configuredSecret = nuxt.options.runtimeConfig?.betterAuthSecret as string | undefined
     const generatedSecret = await promptForSecret(nuxt.options.rootDir, consola, { configuredSecret, prepare: Boolean(nuxt.options._prepare) })
     if (generatedSecret)
-      process.env.BETTER_AUTH_SECRET = generatedSecret
+      process.env.NUXT_BETTER_AUTH_SECRET = generatedSecret
 
     await createDefaultAuthConfigFiles(nuxt)
   },
diff --git a/src/module/runtime.ts b/src/module/runtime.ts
@@ -66,14 +66,14 @@ export function setupRuntimeConfig(input: SetupRuntimeConfigInput): { useHubKV:
   }
 
   const currentSecret = nuxt.options.runtimeConfig.betterAuthSecret as string | undefined
-  nuxt.options.runtimeConfig.betterAuthSecret = currentSecret || process.env.BETTER_AUTH_SECRET || ''
+  nuxt.options.runtimeConfig.betterAuthSecret = currentSecret || process.env.NUXT_BETTER_AUTH_SECRET || process.env.BETTER_AUTH_SECRET || ''
 
   const betterAuthSecret = nuxt.options.runtimeConfig.betterAuthSecret as string
   if (!nuxt.options.dev && !nuxt.options._prepare && !betterAuthSecret) {
-    throw new Error('[nuxt-better-auth] BETTER_AUTH_SECRET is required in production. Set BETTER_AUTH_SECRET or NUXT_BETTER_AUTH_SECRET environment variable.')
+    throw new Error('[nuxt-better-auth] NUXT_BETTER_AUTH_SECRET is required in production. Set NUXT_BETTER_AUTH_SECRET or BETTER_AUTH_SECRET environment variable.')
   }
   if (betterAuthSecret && betterAuthSecret.length < 32) {
-    throw new Error('[nuxt-better-auth] BETTER_AUTH_SECRET must be at least 32 characters for security')
+    throw new Error('[nuxt-better-auth] NUXT_BETTER_AUTH_SECRET must be at least 32 characters for security')
   }
 
   nuxt.options.runtimeConfig.auth = defu(nuxt.options.runtimeConfig.auth as Record<string, unknown>, {
diff --git a/src/module/secret.ts b/src/module/secret.ts
@@ -4,6 +4,9 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'pathe'
 import { isCI, isTest } from 'std-env'
 
+const DEFAULT_SECRET_ENV = 'NUXT_BETTER_AUTH_SECRET'
+const FALLBACK_SECRET_ENV = 'BETTER_AUTH_SECRET'
+
 const generateSecret = () => randomBytes(32).toString('hex')
 
 function readEnvFile(rootDir: string): string {
@@ -12,16 +15,19 @@ function readEnvFile(rootDir: string): string {
 }
 
 function hasEnvSecret(rootDir: string): boolean {
-  const match = readEnvFile(rootDir).match(/^BETTER_AUTH_SECRET=(.+)$/m)
-  return !!match && !!match[1] && match[1].trim().length > 0
+  const envFile = readEnvFile(rootDir)
+  return [DEFAULT_SECRET_ENV, FALLBACK_SECRET_ENV].some((name) => {
+    const match = envFile.match(new RegExp(`^${name}=(.+)$`, 'm'))
+    return !!match && !!match[1] && match[1].trim().length > 0
+  })
 }
 
 function appendSecretToEnv(rootDir: string, secret: string): void {
   const envPath = join(rootDir, '.env')
   let content = readEnvFile(rootDir)
   if (content.length > 0 && !content.endsWith('\n'))
     content += '\n'
-  content += `BETTER_AUTH_SECRET=${secret}\n`
+  content += `${DEFAULT_SECRET_ENV}=${secret}\n`
   writeFileSync(envPath, content, 'utf-8')
 }
 
@@ -35,23 +41,23 @@ export async function promptForSecret(rootDir: string, consola: ConsolaInstance,
   if (configuredSecret)
     return undefined
 
-  if (process.env.BETTER_AUTH_SECRET || hasEnvSecret(rootDir))
+  if (process.env.NUXT_BETTER_AUTH_SECRET || process.env.BETTER_AUTH_SECRET || hasEnvSecret(rootDir))
     return undefined
 
   const hasTty = Boolean(process.stdin.isTTY && process.stdout.isTTY)
   if (options.prepare || !hasTty) {
-    consola.warn('[nuxt-better-auth] Skipping BETTER_AUTH_SECRET prompt (non-interactive). Set BETTER_AUTH_SECRET or NUXT_BETTER_AUTH_SECRET.')
+    consola.warn('[nuxt-better-auth] Skipping NUXT_BETTER_AUTH_SECRET prompt (non-interactive). Set NUXT_BETTER_AUTH_SECRET or BETTER_AUTH_SECRET.')
     return undefined
   }
 
   if (isCI || isTest) {
     const secret = generateSecret()
     appendSecretToEnv(rootDir, secret)
-    consola.info('Generated BETTER_AUTH_SECRET and added to .env (CI/test mode)')
+    consola.info('Generated NUXT_BETTER_AUTH_SECRET and added to .env (CI/test mode)')
     return secret
   }
 
-  consola.box('BETTER_AUTH_SECRET is required for authentication.\nThis will be appended to your .env file.')
+  consola.box('NUXT_BETTER_AUTH_SECRET is required for authentication.\nThis will be appended to your .env file.\nBETTER_AUTH_SECRET is still supported as a fallback.')
   const choice = await consola.prompt('How do you want to set it?', {
     type: 'select',
     options: [
@@ -63,7 +69,7 @@ export async function promptForSecret(rootDir: string, consola: ConsolaInstance,
   }) as 'generate' | 'paste' | 'skip' | symbol
 
   if (typeof choice === 'symbol' || choice === 'skip') {
-    consola.warn('Skipping BETTER_AUTH_SECRET. Auth will fail without it in production.')
+    consola.warn('Skipping NUXT_BETTER_AUTH_SECRET. Auth will fail without it in production.')
     return undefined
   }
 
@@ -81,13 +87,13 @@ export async function promptForSecret(rootDir: string, consola: ConsolaInstance,
   }
 
   const preview = `${secret.slice(0, 8)}...${secret.slice(-4)}`
-  const confirm = await consola.prompt(`Add to .env:\nBETTER_AUTH_SECRET=${preview}\nProceed?`, { type: 'confirm', initial: true, cancel: 'null' }) as boolean | symbol
+  const confirm = await consola.prompt(`Add to .env:\n${DEFAULT_SECRET_ENV}=${preview}\nProceed?`, { type: 'confirm', initial: true, cancel: 'null' }) as boolean | symbol
   if (typeof confirm === 'symbol' || !confirm) {
     consola.info('Cancelled. Secret not written.')
     return undefined
   }
 
   appendSecretToEnv(rootDir, secret)
-  consola.success('Added BETTER_AUTH_SECRET to .env')
+  consola.success('Added NUXT_BETTER_AUTH_SECRET to .env')
   return secret
 }
diff --git a/test/non-tty-secret-prompt.test.ts b/test/non-tty-secret-prompt.test.ts
@@ -3,6 +3,31 @@ import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 
 const repoDir = fileURLToPath(new URL('..', import.meta.url))
+const nonInteractiveScript = `
+import { createJiti } from 'jiti'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const jiti = createJiti(process.cwd(), { interopDefault: true, moduleCache: false })
+const { promptForSecret } = await jiti.import('./src/module/secret.ts')
+
+let promptCalls = 0
+const consola = {
+  warn: (...args) => console.log(String(args[0] ?? '')),
+  info: () => {},
+  success: () => {},
+  box: () => {},
+  prompt: async () => {
+    promptCalls++
+    throw new Error('prompt called')
+  },
+}
+
+const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nuxt-better-auth-secret-'))
+await promptForSecret(rootDir, consola, { prepare: true })
+console.log('PROMPT_CALLS=' + promptCalls)
+`
 
 function createNonTestEnv(): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { ...process.env }
@@ -27,46 +52,45 @@ function createNonTestEnv(): NodeJS.ProcessEnv {
   return env
 }
 
+function runPromptScript(env: NodeJS.ProcessEnv) {
+  return spawnSync(process.execPath, ['--input-type=module', '-e', nonInteractiveScript], {
+    cwd: repoDir,
+    env,
+    encoding: 'utf8',
+    timeout: 60_000,
+  })
+}
+
 describe('promptForSecret', () => {
   it('skips prompting in non-interactive/prepare mode', () => {
     const env = createNonTestEnv()
+    const run = runPromptScript(env)
 
-    const script = `
-import { createJiti } from 'jiti'
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-
-const jiti = createJiti(process.cwd(), { interopDefault: true, moduleCache: false })
-const { promptForSecret } = await jiti.import('./src/module/secret.ts')
+    expect(run.status, `node script failed:\n${run.stdout}\n${run.stderr}`).toBe(0)
+    const output = `${run.stdout}\n${run.stderr}`
+    expect(output).toContain('Skipping NUXT_BETTER_AUTH_SECRET prompt')
+    expect(output).toContain('PROMPT_CALLS=0')
+  })
 
-let promptCalls = 0
-const consola = {
-  warn: (...args) => console.log(String(args[0] ?? '')),
-  info: () => {},
-  success: () => {},
-  box: () => {},
-  prompt: async () => {
-    promptCalls++
-    throw new Error('prompt called')
-  },
-}
+  it('skips prompting when NUXT_BETTER_AUTH_SECRET is already set', () => {
+    const env = createNonTestEnv()
+    env.NUXT_BETTER_AUTH_SECRET = 'test-secret-for-testing-only-32chars'
+    const run = runPromptScript(env)
 
-const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nuxt-better-auth-secret-'))
-await promptForSecret(rootDir, consola, { prepare: true })
-console.log('PROMPT_CALLS=' + promptCalls)
-`
+    expect(run.status, `node script failed:\n${run.stdout}\n${run.stderr}`).toBe(0)
+    const output = `${run.stdout}\n${run.stderr}`
+    expect(output).not.toContain('Skipping NUXT_BETTER_AUTH_SECRET prompt')
+    expect(output).toContain('PROMPT_CALLS=0')
+  })
 
-    const run = spawnSync(process.execPath, ['--input-type=module', '-e', script], {
-      cwd: repoDir,
-      env,
-      encoding: 'utf8',
-      timeout: 60_000,
-    })
+  it('skips prompting when BETTER_AUTH_SECRET fallback is already set', () => {
+    const env = createNonTestEnv()
+    env.BETTER_AUTH_SECRET = 'test-secret-for-testing-only-32chars'
+    const run = runPromptScript(env)
 
     expect(run.status, `node script failed:\n${run.stdout}\n${run.stderr}`).toBe(0)
     const output = `${run.stdout}\n${run.stderr}`
-    expect(output).toContain('Skipping BETTER_AUTH_SECRET prompt')
+    expect(output).not.toContain('Skipping NUXT_BETTER_AUTH_SECRET prompt')
     expect(output).toContain('PROMPT_CALLS=0')
   })
 })
diff --git a/test/runtime-config.test.ts b/test/runtime-config.test.ts

Original file line number	Diff line number	Diff line change
`@@ -66,14 +66,14 @@ export function setupRuntimeConfig(input: SetupRuntimeConfigInput): { useHubKV:`
`66`	`66`	`}`
`67`	`67`
`68`	`68`	`const currentSecret = nuxt.options.runtimeConfig.betterAuthSecret as string \| undefined`
`69`		`- nuxt.options.runtimeConfig.betterAuthSecret = currentSecret \|\| process.env.BETTER_AUTH_SECRET \|\| ''`
	`69`	`+ nuxt.options.runtimeConfig.betterAuthSecret = currentSecret \|\| process.env.NUXT_BETTER_AUTH_SECRET \|\| process.env.BETTER_AUTH_SECRET \|\| ''`
`70`	`70`
`71`	`71`	`const betterAuthSecret = nuxt.options.runtimeConfig.betterAuthSecret as string`
`72`	`72`	`if (!nuxt.options.dev && !nuxt.options._prepare && !betterAuthSecret) {`
`73`		`- throw new Error('[nuxt-better-auth] BETTER_AUTH_SECRET is required in production. Set BETTER_AUTH_SECRET or NUXT_BETTER_AUTH_SECRET environment variable.')`
	`73`	`+ throw new Error('[nuxt-better-auth] NUXT_BETTER_AUTH_SECRET is required in production. Set NUXT_BETTER_AUTH_SECRET or BETTER_AUTH_SECRET environment variable.')`
`74`	`74`	`}`
`75`	`75`	`if (betterAuthSecret && betterAuthSecret.length < 32) {`
`76`		`- throw new Error('[nuxt-better-auth] BETTER_AUTH_SECRET must be at least 32 characters for security')`
	`76`	`+ throw new Error('[nuxt-better-auth] NUXT_BETTER_AUTH_SECRET must be at least 32 characters for security')`
`77`	`77`	`}`
`78`	`78`
`79`	`79`	`nuxt.options.runtimeConfig.auth = defu(nuxt.options.runtimeConfig.auth as Record<string, unknown>, {`