feat: add KV secondary storage and baseURL auto-detection

Author: onmax

docs/content/1.getting-started/2.configuration.md

@@ -3,7 +3,33 @@ title: Server Configuration
 description: Create `server/auth.config.ts` with your Better Auth setup.
 ---
 
-The module requires a Better Auth config file at `server/auth.config.ts`.  
+## Module Options
+
+Configure in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  auth: {
+    redirects: { login: '/login', guest: '/' },
+    secondaryStorage: true, // Enable KV for faster session lookups
+  }
+})
+```
+
+### secondaryStorage
+
+When enabled, uses NuxtHub KV (`hub:kv`) as secondary storage for sessions.
+This reduces database queries by caching sessions in KV with TTL support.
+
+**Requirements:**
+- `hub.kv: true` must be set in nuxt.config
+- If KV is not enabled, the module logs a warning and disables secondaryStorage
+
+---
+
+## Server Auth Config
+
+The module requires a Better Auth config file at `server/auth.config.ts`.
 It must export a default function created with `defineServerAuth`.
 
 ## Example

docs/content/2.core-concepts/0.how-it-works.md

@@ -17,7 +17,17 @@ The module validates both files exist at build time.
 - `serverAuth()` creates and caches a Better Auth instance by calling your config and injecting:
   - NuxtHub database via the Drizzle adapter
   - `runtimeConfig.betterAuthSecret`
-  - `runtimeConfig.public.siteUrl` as `baseURL`
+  - `baseURL` (auto-detected, see below)
+  - Optional KV secondary storage when `auth.secondaryStorage: true`
+
+### BaseURL Detection
+
+The module auto-detects the base URL from:
+1. `runtimeConfig.public.siteUrl` (recommended)
+2. Fallback: current request origin via `getRequestURL()`
+
+Setting `NUXT_PUBLIC_SITE_URL` is optional but recommended for production.
+
 - A catch-all API handler at `/api/auth/**` that forwards to Better Auth.
 - Nitro middleware for `/api/**` that enforces `routeRules.role` using `requireUserSession(...)`.
 

src/module.ts

@@ -13,7 +13,7 @@ export type { BetterAuthModuleOptions } from './runtime/config'
 
 export default defineNuxtModule<BetterAuthModuleOptions>({
   meta: { name: '@onmax/nuxt-better-auth', configKey: 'auth', compatibility: { nuxt: '>=3.0.0' } },
-  defaults: { redirects: { login: '/login', guest: '/' } },
+  defaults: { redirects: { login: '/login', guest: '/' }, secondaryStorage: false },
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url)
 
@@ -29,6 +29,16 @@ export default defineNuxtModule<BetterAuthModuleOptions>({
     if (!clientConfigExists)
       throw new Error('[@onmax/nuxt-better-auth] Missing app/auth.client.ts - export createAppAuthClient()')
 
+    // Validate KV is enabled if secondaryStorage requested
+    let secondaryStorageEnabled = options.secondaryStorage ?? false
+    if (secondaryStorageEnabled) {
+      const hub = nuxt.options.hub as { kv?: boolean } | undefined
+      if (!hub?.kv) {
+        console.warn('[nuxt-better-auth] secondaryStorage requires hub.kv: true in nuxt.config.ts. Disabling.')
+        secondaryStorageEnabled = false
+      }
+    }
+
     // Expose module options to runtime config
     nuxt.options.runtimeConfig.public = nuxt.options.runtimeConfig.public || {}
     nuxt.options.runtimeConfig.public.auth = defu(nuxt.options.runtimeConfig.public.auth as Record<string, unknown>, {
@@ -38,6 +48,9 @@ export default defineNuxtModule<BetterAuthModuleOptions>({
       },
     })
 
+    // Private runtime config (server-only)
+    nuxt.options.runtimeConfig.auth = defu(nuxt.options.runtimeConfig.auth as Record<string, unknown>, { secondaryStorage: secondaryStorageEnabled })
+
     // Register #nuxt-better-auth alias for type augmentation
     nuxt.options.alias['#nuxt-better-auth'] = resolver.resolve('./runtime/types/augment')
 

src/runtime/config.ts

@@ -22,13 +22,20 @@ export interface BetterAuthModuleOptions {
     login?: string // default: '/login'
     guest?: string // default: '/'
   }
+  /** Enable KV secondary storage for sessions. Requires hub.kv: true */
+  secondaryStorage?: boolean
 }
 
 // Runtime config type for public.auth
 export interface AuthRuntimeConfig {
   redirects: { login: string, guest: string }
 }
 
+// Private runtime config (server-only)
+export interface AuthPrivateRuntimeConfig {
+  secondaryStorage: boolean
+}
+
 export function defineServerAuth<T extends ServerAuthConfig>(config: (ctx: ServerAuthContext) => T): (ctx: ServerAuthContext) => T {
   return config
 }

src/runtime/server/utils/auth.ts

@@ -1,26 +1,61 @@
 import createServerAuth from '#auth/server'
-import { useRuntimeConfig } from '#imports'
+import { useEvent, useRuntimeConfig } from '#imports'
 import { betterAuth } from 'better-auth'
 import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { getRequestURL } from 'h3'
 import { db, schema } from 'hub:db'
 
 type AuthInstance = ReturnType<typeof betterAuth>
 let _auth: AuthInstance | undefined
 
+function getBaseURL(siteUrl?: string): string {
+  if (siteUrl)
+    return siteUrl
+
+  // Fallback: detect from current request
+  try {
+    const event = useEvent()
+    return getRequestURL(event).origin
+  }
+  catch {
+    return ''
+  }
+}
+
+let _kv: typeof import('hub:kv').kv | undefined
+
+async function getKV() {
+  if (!_kv) {
+    const { kv } = await import('hub:kv')
+    _kv = kv
+  }
+  return _kv
+}
+
+function createSecondaryStorage() {
+  return {
+    get: async (key: string) => (await getKV()).get(`_auth:${key}`),
+    set: async (key: string, value: unknown, ttl?: number) => (await getKV()).set(`_auth:${key}`, value, { ttl }),
+    delete: async (key: string) => (await getKV()).del(`_auth:${key}`),
+  }
+}
+
 export function serverAuth(): AuthInstance {
   if (_auth)
     return _auth
 
   const runtimeConfig = useRuntimeConfig()
+  const authConfig = runtimeConfig.auth as { secondaryStorage?: boolean } | undefined
 
   // User's config function receives context with db
   const userConfig = createServerAuth({ runtimeConfig, db })
 
   _auth = betterAuth({
     ...userConfig,
     database: drizzleAdapter(db, { provider: 'sqlite', schema }),
+    secondaryStorage: authConfig?.secondaryStorage ? createSecondaryStorage() : undefined,
     secret: runtimeConfig.betterAuthSecret,
-    baseURL: runtimeConfig.public.siteUrl,
+    baseURL: getBaseURL(runtimeConfig.public.siteUrl as string | undefined),
   })
 
   return _auth