fix: Prevents database connection issues during build

Addresses issues where database connections during build or prerendering could cause the build process to hang.

This is achieved by:
- Adding a utility to detect build time based on environment variables and process arguments.
- Excluding the nuxt-users API routes from Nitro's prerendering process, preventing premature database access attempts.
- Skipping database connection checks during the build phase to prevent build failures.
- Throwing an error if a database connection is attempted during build time to signal misconfiguration.

This ensures a more robust build process and prevents unexpected errors due to database unavailability during build time.

Author: rrd108

src/module.ts

@@ -240,6 +240,18 @@ export default defineNuxtModule<RuntimeModuleOptions>({
       nitroConfig.scanDirs = nitroConfig.scanDirs || []
       nitroConfig.scanDirs.push(resolver.resolve('./runtime/server/tasks'))
 
+      // Automatically exclude nuxt-users API routes from prerendering to prevent build hangs
+      nitroConfig.prerender = nitroConfig.prerender || {}
+      nitroConfig.prerender.ignore = nitroConfig.prerender.ignore || []
+      
+      const apiBasePath = (nuxt.options.runtimeConfig.nuxtUsers as ModuleOptions).apiBasePath || defaultOptions.apiBasePath
+      const ignorePattern = `${apiBasePath}/**`
+      
+      if (!nitroConfig.prerender.ignore.includes(ignorePattern)) {
+        nitroConfig.prerender.ignore.push(ignorePattern)
+        console.log(`[Nuxt Users] 🔧 Automatically excluding "${ignorePattern}" from prerendering to prevent build hangs`)
+      }
+
       // NOTE: We no longer configure the database connection here at build time
       // because it prevents runtime environment variables from being used.
       // The database connection is now established at runtime through useDb()

src/runtime/plugin.ts

@@ -1,15 +1,24 @@
 import { defineNuxtPlugin, useRuntimeConfig } from '#app'
 import type { ModuleOptions } from './utils/imports'
-import { checkTableExists } from './server/utils'
+import { checkTableExists, isBuildTime } from './server/utils'
 
 export default defineNuxtPlugin(async (_nuxtApp) => {
   const { nuxtUsers } = useRuntimeConfig()
-  // const { public: { nuxtUsers: publicNuxtUsers } } = useRuntimeConfig()
   const options = nuxtUsers as ModuleOptions
-  // const publicOptions = publicNuxtUsers as ModuleOptions
 
-  const hasMigrationsTable = await checkTableExists(options, options.tables.migrations)
-  if (!hasMigrationsTable) {
-    console.warn('[Nuxt Users] ⚠️  Migrations table does not exist, you should run the migration script to create it by running: npx nuxt-users migrate')
+  // Skip database checks during build/prerendering to prevent hanging
+  if (isBuildTime()) {
+    console.log('[Nuxt Users] 🔧 Build-time detected, skipping database connection checks')
+    return
+  }
+
+  try {
+    const hasMigrationsTable = await checkTableExists(options, options.tables.migrations)
+    if (!hasMigrationsTable) {
+      console.warn('[Nuxt Users] ⚠️  Migrations table does not exist, you should run the migration script to create it by running: npx nuxt-users migrate')
+    }
+  } catch (error) {
+    // If database connection fails during runtime, warn but don't crash
+    console.warn('[Nuxt Users] ⚠️  Database connection failed during initialization:', error instanceof Error ? error.message : 'Unknown error')
   }
 })

src/runtime/server/utils/build-time.ts

@@ -0,0 +1,22 @@
+/**
+ * Detects if we're running during build/prerendering phase
+ * During prerendering, Nuxt starts a temporary server that should not connect to the database
+ */
+export const isBuildTime = (): boolean => {
+  // Check for Nitro prerendering environment variables
+  if (process.env.NITRO_PRESET === 'nitro-prerender' || process.env.NUXT_ENV === 'prerender') {
+    return true
+  }
+  
+  // Check if we're in a prerendering context
+  if (process.env.NODE_ENV === 'production' && process.argv.includes('--prerender')) {
+    return true
+  }
+  
+  // Check for common build/prerender indicators
+  const buildIndicators = ['prerender', 'build', 'generate']
+  return buildIndicators.some(indicator => 
+    process.argv.join(' ').toLowerCase().includes(indicator) ||
+    process.env.npm_lifecycle_event?.includes(indicator)
+  )
+}

src/runtime/server/utils/db.ts

@@ -42,7 +42,14 @@ export const getConnector = async (name: string) => {
   }
 }
 
+import { isBuildTime } from './build-time'
+
 export const useDb = async (options: ModuleOptions): Promise<Database> => {
+  // During build/prerendering, throw an error to prevent hanging
+  if (isBuildTime()) {
+    throw new Error('[Nuxt Users] Database connections are not available during build/prerendering phase. This should not happen - please check your prerender configuration.')
+  }
+
   const cacheKey = JSON.stringify(options.connector)
 
   if (dbCache.has(cacheKey)) {

src/runtime/server/utils/index.ts

@@ -1,5 +1,6 @@
 // Internal utils - used by module's API routes, middleware, services, tasks
 export { useDb, checkTableExists } from './db'
+export { isBuildTime } from './build-time'
 export { createUser, findUserByEmail, updateUserPassword, getCurrentUserFromToken, hasAnyUsers, deleteExpiredPersonalAccessTokens, deleteTokensWithoutExpiration, cleanupPersonalAccessTokens, revokeUserTokens, getLastLoginTime, findUserById, updateUser, deleteUser } from './user'
 export { createUsersTable } from './create-users-table'
 export { createPersonalAccessTokensTable } from './create-personal-access-tokens-table'

test/unit/build-time-detection.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { isBuildTime } from '../../src/runtime/server/utils/build-time'
+
+describe('Build-time Detection', () => {
+  const originalEnv = process.env
+  const originalArgv = process.argv
+
+  beforeEach(() => {
+    // Reset environment
+    process.env = { ...originalEnv }
+    process.argv = [...originalArgv]
+  })
+
+  afterEach(() => {
+    // Restore environment
+    process.env = originalEnv
+    process.argv = originalArgv
+  })
+
+  describe('Environment Detection', () => {
+    it('should detect NITRO_PRESET=nitro-prerender', () => {
+      process.env.NITRO_PRESET = 'nitro-prerender'
+      expect(isBuildTime()).toBe(true)
+    })
+
+    it('should detect NUXT_ENV=prerender', () => {
+      process.env.NUXT_ENV = 'prerender'
+      expect(isBuildTime()).toBe(true)
+    })
+
+    it('should detect build indicators in npm_lifecycle_event', () => {
+      process.env.npm_lifecycle_event = 'build'
+      expect(isBuildTime()).toBe(true)
+    })
+
+    it('should detect prerender in process arguments', () => {
+      process.argv = ['node', 'nuxt', 'build', '--prerender']
+      expect(isBuildTime()).toBe(true)
+    })
+
+    it('should return false when not in build time', () => {
+      // Reset to normal runtime environment
+      delete process.env.NITRO_PRESET
+      delete process.env.NUXT_ENV
+      delete process.env.npm_lifecycle_event
+      process.argv = ['node', 'server.js']
+      
+      expect(isBuildTime()).toBe(false)
+    })
+  })
+
+  describe('Database Connection Prevention', () => {
+    it('should prevent database connections during build time', async () => {
+      // Set build-time environment
+      process.env.NITRO_PRESET = 'nitro-prerender'
+      
+      // Import the db module
+      const { useDb } = await import('../../src/runtime/server/utils/db')
+      
+      const mockOptions = {
+        connector: { name: 'sqlite' as const, options: { path: './test.db' } },
+        tables: { migrations: 'migrations', users: 'users', personalAccessTokens: 'tokens', passwordResetTokens: 'reset_tokens' },
+        apiBasePath: '/api/nuxt-users',
+        passwordResetUrl: '/reset',
+        emailConfirmationUrl: '/confirm',
+        auth: { whitelist: [], tokenExpiration: 1440, rememberMeExpiration: 30, permissions: {} },
+        passwordValidation: {
+          minLength: 8,
+          requireUppercase: true,
+          requireLowercase: true,
+          requireNumbers: true,
+          requireSpecialChars: true,
+          preventCommonPasswords: true
+        },
+        hardDelete: false
+      }
+      
+      // Should throw an error indicating build-time detection
+      await expect(useDb(mockOptions))
+        .rejects
+        .toThrow('Database connections are not available during build/prerendering phase')
+    })
+  })
+
+  describe('Production Build Scenarios', () => {
+    it('should detect production builds with prerender flag', () => {
+      process.env.NODE_ENV = 'production'
+      process.argv = ['node', 'nuxt', 'build', '--prerender']
+      
+      expect(isBuildTime()).toBe(true)
+    })
+
+    it('should detect generate command', () => {
+      process.argv = ['node', 'nuxt', 'generate']
+      
+      expect(isBuildTime()).toBe(true)
+    })
+
+    it('should not detect regular production server', () => {
+      process.env.NODE_ENV = 'production'
+      process.argv = ['node', 'server.js']
+      delete process.env.npm_lifecycle_event
+      
+      expect(isBuildTime()).toBe(false)
+    })
+  })
+})