fix(auth): preserve nuxthub db package imports in prerender builds (#305)

onmax · web-flow · commit f30fdde946f0 · 2026-04-17T09:55:55.000+02:00
diff --git a/docs/content/3.guides/9.production-deployment.md b/docs/content/3.guides/9.production-deployment.md
@@ -5,7 +5,7 @@ description: Checklist and best practices for deploying Nuxt Better Auth in prod
 
 ## Environment Variables
 
-Production requires these environment variables at runtime:
+Production requires these environment variables:
 
 ```ini [.env.production]
 # Required: 32+ character secret for session encryption
@@ -25,7 +25,7 @@ GOOGLE_CLIENT_SECRET="..."
 node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 ```
 
-The secret must be at least 32 characters. Shorter secrets will cause auth initialization to throw an error at runtime.
+The secret must be at least 32 characters. Shorter secrets will cause the module to throw an error.
 
 ## Security Checklist
 
@@ -79,10 +79,6 @@ export default defineEventHandler((event) => {
 
 For production, consider using Cloudflare rate limiting or a Redis-backed solution.
 
-### Separate Build And Runtime Environments
-
-Some platforms, including Cloudflare deployments, expose build-time and runtime environment variables separately. `NUXT_BETTER_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.
@@ -121,11 +117,7 @@ export default defineNuxtConfig({
 
 ### "NUXT_BETTER_AUTH_SECRET must be at least 32 characters"
 
-Your secret is too short. Generate a new one using the command above. This error is raised when auth initializes at runtime. `BETTER_AUTH_SECRET` is still accepted as a fallback, but `NUXT_BETTER_AUTH_SECRET` is the recommended variable.
-
-### "NUXT_BETTER_AUTH_SECRET is required in production"
-
-The deployed server runtime could not resolve an auth secret. Set `NUXT_BETTER_AUTH_SECRET` or `BETTER_AUTH_SECRET` in the runtime environment for your app.
+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/package.json b/package.json
@@ -92,6 +92,7 @@
     "eslint": "^10.0.3",
     "npm-agentskills": "https://pkg.pr.new/onmax/npm-agentskills@394499e",
     "nuxt": "^4.3.1",
+    "postgres": "^3.4.9",
     "tinyexec": "^1.0.2",
     "typescript": "~5.9.3",
     "vitest": "^4.0.18",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/module.ts b/src/module.ts
@@ -210,8 +210,21 @@ export { schema }
         runtimeTypesPath: resolver.resolve('./runtime/types'),
       })
 
-      if (hasHubDb)
+      if (hasHubDb) {
+        // Keep @nuxthub/db as a bare specifier during Nitro bundling so the
+        // prerender entry doesn't rewrite it to a broken relative path like
+        // `../../../../../../../../@nuxthub/db/db.mjs` when `.nuxt` lives
+        // inside `node_modules/.cache/nuxt/`.
+        // @ts-expect-error Nitro augments NuxtHooks at runtime.
+        nuxt.hook('nitro:config', (nitroConfig: { externals?: { external?: string[] } }) => {
+          nitroConfig.externals ||= {}
+          nitroConfig.externals.external ||= []
+          if (!nitroConfig.externals.external.includes('@nuxthub/db'))
+            nitroConfig.externals.external.push('@nuxthub/db')
+        })
+
         await setupBetterAuthSchema(nuxt, serverConfigPath, options, consola, options.hubSecondaryStorage ?? false)
+      }
     }
 
     registerSharedTypeTemplates({
diff --git a/src/module/runtime.ts b/src/module/runtime.ts
@@ -68,6 +68,14 @@ export function setupRuntimeConfig(input: SetupRuntimeConfigInput): { useHubKV:
   const currentSecret = nuxt.options.runtimeConfig.betterAuthSecret as string | undefined
   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] 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] 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>, {
     hubSecondaryStorage: options.hubSecondaryStorage ?? false,
   }) as AuthPrivateRuntimeConfig
diff --git a/src/runtime/server/utils/auth.ts b/src/runtime/server/utils/auth.ts
@@ -10,7 +10,6 @@ import { getRequestHost, getRequestProtocol } from 'h3'
 import { useRuntimeConfig } from 'nitropack/runtime'
 import { withoutProtocol } from 'ufo'
 import { resolveCustomSecondaryStorageRequirement } from './custom-secondary-storage'
-import { validateAuthSecret } from './validate-secret'
 
 type AuthOptions = ReturnType<typeof createServerAuth>
 type AuthInstance = ReturnType<typeof betterAuth<AuthOptions>>
@@ -257,7 +256,6 @@ export function serverAuth(event?: H3Event): AuthInstance {
   if (cached)
     return cached
 
-  const betterAuthSecret = validateAuthSecret(runtimeConfig.betterAuthSecret)
   const database = createDatabase()
   const userConfig = createServerAuth({ runtimeConfig, db }) as BetterAuthOptions & {
     secondaryStorage?: BetterAuthOptions['secondaryStorage']
@@ -277,7 +275,7 @@ export function serverAuth(event?: H3Event): AuthInstance {
     ...userConfig,
     ...(database && { database }),
     ...(hubSecondaryStorage === true && { secondaryStorage: createSecondaryStorage() }),
-    secret: betterAuthSecret,
+    secret: runtimeConfig.betterAuthSecret,
     baseURL: siteUrl,
     trustedOrigins,
   })
diff --git a/src/runtime/server/utils/validate-secret.ts b/src/runtime/server/utils/validate-secret.ts
diff --git a/test/cases/nuxthub-prerender-db/.nuxtrc b/test/cases/nuxthub-prerender-db/.nuxtrc
@@ -0,0 +1 @@
+setups.@onmax/nuxt-better-auth="0.0.2-alpha.31"
diff --git a/test/cases/nuxthub-prerender-db/app/app.vue b/test/cases/nuxthub-prerender-db/app/app.vue
@@ -0,0 +1,3 @@
+<template>
+  <NuxtPage />
+</template>
diff --git a/test/cases/nuxthub-prerender-db/app/auth.config.ts b/test/cases/nuxthub-prerender-db/app/auth.config.ts
@@ -0,0 +1,3 @@
+import { defineClientAuth } from '../../../../src/runtime/config'
+
+export default defineClientAuth({})
diff --git a/test/cases/nuxthub-prerender-db/app/pages/index.vue b/test/cases/nuxthub-prerender-db/app/pages/index.vue
@@ -0,0 +1,3 @@
+<template>
+  <main>NuxtHub Hyperdrive Prerender Test</main>
+</template>
diff --git a/test/cases/nuxthub-prerender-db/nuxt.config.ts b/test/cases/nuxthub-prerender-db/nuxt.config.ts
@@ -0,0 +1,23 @@
+export default defineNuxtConfig({
+  modules: ['@nuxthub/core', '../../../src/module'],
+
+  hub: {
+    db: {
+      dialect: 'postgresql',
+      driver: 'postgres-js',
+      applyMigrationsDuringBuild: false,
+      connection: {
+        url: process.env.DATABASE_URL || '',
+      },
+    },
+  },
+
+  runtimeConfig: {
+    betterAuthSecret: 'test-secret-for-testing-only-32chars!',
+    public: { siteUrl: 'http://localhost:3000' },
+  },
+
+  routeRules: {
+    '/': { prerender: true },
+  },
+})
diff --git a/test/cases/nuxthub-prerender-db/server/auth.config.ts b/test/cases/nuxthub-prerender-db/server/auth.config.ts
@@ -0,0 +1,6 @@
+import { defineServerAuth } from '../../../../src/runtime/config'
+
+export default defineServerAuth({
+  appName: 'NuxtHub Prerender DB Test',
+  emailAndPassword: { enabled: true },
+})
diff --git a/test/nuxthub-prerender-db-import.test.ts b/test/nuxthub-prerender-db-import.test.ts
@@ -0,0 +1,54 @@
+import { spawnSync } from 'node:child_process'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'pathe'
+import { describe, expect, it } from 'vitest'
+
+const fixtureDir = fileURLToPath(new URL('./cases/nuxthub-prerender-db', import.meta.url))
+const env = {
+  ...process.env,
+  BETTER_AUTH_SECRET: 'test-secret-for-testing-only-32chars',
+  DATABASE_URL: 'postgresql://postgres:postgres@127.0.0.1:5432/nuxt_better_auth_prerender_demo',
+}
+
+function walk(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory())
+      return walk(path)
+    return [path]
+  })
+}
+
+function readGeneratedPrerenderOutput(): string {
+  const prerenderDir = join(fixtureDir, '.nuxt/prerender')
+  if (!statSync(prerenderDir, { throwIfNoEntry: false })?.isDirectory())
+    return ''
+
+  return walk(prerenderDir)
+    .filter(path => /\.(?:mjs|js)$/.test(path))
+    .map(path => readFileSync(path, 'utf8'))
+    .join('\n')
+}
+
+describe('nuxthub prerender @nuxthub/db imports', () => {
+  it('keeps @nuxthub/db as an external import in prerender output', () => {
+    const build = spawnSync('npx', ['nuxi', 'build'], {
+      cwd: fixtureDir,
+      env,
+      encoding: 'utf8',
+    })
+
+    expect(build.status, `nuxi build failed:\n${build.stdout}\n${build.stderr}`).toBe(0)
+
+    const generatedDatabase = readFileSync(`${fixtureDir}/.nuxt/better-auth/database.mjs`, 'utf8')
+    const prerenderOutput = readGeneratedPrerenderOutput()
+
+    expect(generatedDatabase).toContain('import { db } from \'@nuxthub/db\'')
+    // The bug emits a broken relative path like `../../../../../../../../@nuxthub/db/db.mjs`
+    // that escapes the build dir and crashes the prerender step.
+    expect(prerenderOutput).not.toMatch(/\.\.\/\.\.\/\.\.\/\.\.\/[^'"`]*@nuxthub\/db/)
+    // The generated better-auth database template must not be inlined into the prerender output.
+    expect(prerenderOutput).not.toContain('node_modules/.cache/nuxt/.nuxt/better-auth/database.mjs')
+  }, 120_000)
+})
diff --git a/test/runtime-config.test.ts b/test/runtime-config.test.ts
@@ -135,7 +135,7 @@ describe('setupRuntimeConfig secret resolution', () => {
     expect((nuxt.options as any).runtimeConfig.betterAuthSecret).toBe('fallback-secret-for-testing-only-32chars')
   })
 
-  it('does not throw in production when no secret is configured', () => {
+  it('throws in production when no secret is configured', () => {
     const nuxt = createNuxtWithRuntimeConfig()
     nuxt.options.dev = false
     const consola = createConsolaMock()
@@ -147,8 +147,7 @@ describe('setupRuntimeConfig secret resolution', () => {
       databaseProvider: 'none',
       hasNuxtHub: false,
       consola,
-    })).not.toThrow()
-    expect((nuxt.options as any).runtimeConfig.betterAuthSecret).toBe('')
+    })).toThrow('NUXT_BETTER_AUTH_SECRET is required in production')
   })
 })
 
diff --git a/test/server-auth-runtime-validation.test.ts b/test/server-auth-runtime-validation.test.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+setups.@onmax/nuxt-better-auth="0.0.2-alpha.31"`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+<template>`
	`2`	`+ <NuxtPage />`
	`3`	`+</template>`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+import { defineClientAuth } from '../../../../src/runtime/config'`
	`2`	`+`
	`3`	`+export default defineClientAuth({})`