fix: register cache mount under kv on nitro v3

packages/script/src/module.ts

@@ -47,6 +47,7 @@ import {
   addTemplate,
   createResolver,
   defineNuxtModule,
+  getNitroVersion,
   hasNuxtModule,
 } from '@nuxt/kit'
 import { defu } from 'defu'
@@ -1021,7 +1022,18 @@ export default defineNuxtModule<ModuleOptions>({
     // Nitro's default memory storage has no eviction policy. Every proxy and
     // embed cache shares this bounded mount, including proxy-only registries
     // without dedicated server handlers. Preserve application-supplied mounts.
-    ensureNuxtScriptsCacheStorage(nuxt.options.nitro as any, await resolvePath('./runtime/server/utils/lru-cache-driver'))
+    const cacheDriver = await resolvePath('./runtime/server/utils/lru-cache-driver')
+    if (getNitroVersion(nuxt) === 3) {
+      // Nitro v3 merges `kv` from `nitro.config.ts` under the inline Nuxt config, so a
+      // default set here would replace an application mount declared there. Add it
+      // once the options are resolved instead; mounts are read again at build time.
+      nuxt.hook('nitro:init', (nitro) => {
+        ensureNuxtScriptsCacheStorage(nitro.options as any, cacheDriver, 3)
+      })
+    }
+    else {
+      ensureNuxtScriptsCacheStorage(nuxt.options.nitro as any, cacheDriver)
+    }
 
     // Publish enabled endpoints to client for component opt-in checks
     nuxt.options.runtimeConfig.public['nuxt-scripts'] = defu(

packages/script/src/runtime/server/utils/cache-config.ts

@@ -11,11 +11,21 @@ export const NUXT_SCRIPTS_CACHE_MAX_ENTRY_SIZE = 8 * 1024 * 1024
 
 interface NitroOptionsWithStorage {
   storage?: Record<string, unknown>
+  kv?: Record<string, unknown>
 }
 
-export function ensureNuxtScriptsCacheStorage(nitroOptions: NitroOptionsWithStorage, driver: string): void {
-  nitroOptions.storage ||= {}
-  nitroOptions.storage[NUXT_SCRIPTS_CACHE_BASE] ||= {
+/**
+ * Nitro v3 renamed the `storage` option to `kv` (`storage` still works but logs a
+ * deprecation warning), so the mount goes to `kv` there. A mount the application
+ * configured under either key is preserved.
+ */
+export function ensureNuxtScriptsCacheStorage(nitroOptions: NitroOptionsWithStorage, driver: string, nitroVersion: number = 2): void {
+  if (nitroVersion >= 3 && nitroOptions.storage?.[NUXT_SCRIPTS_CACHE_BASE])
+    return
+  const mounts = nitroVersion >= 3
+    ? (nitroOptions.kv ||= {})
+    : (nitroOptions.storage ||= {})
+  mounts[NUXT_SCRIPTS_CACHE_BASE] ||= {
     driver,
     max: NUXT_SCRIPTS_CACHE_MAX_ENTRIES,
     maxSize: NUXT_SCRIPTS_CACHE_MAX_SIZE,

test/unit/cached-upstream-lifecycle.test.ts

@@ -28,6 +28,31 @@ describe('upstream cache storage ownership', () => {
     }))
   })
 
+  it('installs the cache mount under `kv` on Nitro v3', () => {
+    const nitroOptions: { storage?: Record<string, unknown>, kv?: Record<string, unknown> } = {}
+
+    ensureNuxtScriptsCacheStorage(nitroOptions, '/nuxt-scripts/lru-cache-driver', 3)
+
+    expect(nitroOptions.storage).toBeUndefined()
+    expect(nitroOptions.kv?.[NUXT_SCRIPTS_CACHE_BASE]).toEqual(expect.objectContaining({
+      driver: '/nuxt-scripts/lru-cache-driver',
+      max: NUXT_SCRIPTS_CACHE_MAX_ENTRIES,
+    }))
+  })
+
+  it('preserves an application mount under either key on Nitro v3', () => {
+    const userMount = { driver: 'redis' }
+    const legacy: { storage?: Record<string, unknown>, kv?: Record<string, unknown> } = { storage: { [NUXT_SCRIPTS_CACHE_BASE]: userMount } }
+    const current: { storage?: Record<string, unknown>, kv?: Record<string, unknown> } = { kv: { [NUXT_SCRIPTS_CACHE_BASE]: userMount } }
+
+    ensureNuxtScriptsCacheStorage(legacy, '/nuxt-scripts/lru-cache-driver', 3)
+    ensureNuxtScriptsCacheStorage(current, '/nuxt-scripts/lru-cache-driver', 3)
+
+    expect(legacy.kv).toBeUndefined()
+    expect(legacy.storage?.[NUXT_SCRIPTS_CACHE_BASE]).toBe(userMount)
+    expect(current.kv?.[NUXT_SCRIPTS_CACHE_BASE]).toBe(userMount)
+  })
+
   it('puts binary proxy payloads in the bounded Nuxt Scripts cache mount', () => {
     createCachedBinaryFetch('binary-test', 60)