feat: support 'use cache' (#2862)

* test: add integration test cases for use-cache

* feat: add support for default use-cache handler

* test: cleanup after use-cache tests

* test: fix typo in test use cache test helper

* chore: remove unused PrivateCacheEntry properties and add more information in module preamble comment

* chore: remove unneed return to clean up PR diff

Author: pieh

package-lock.json

@@ -77,6 +77,7 @@
     "msw": "^2.0.7",
     "netlify-cli": "^20.1.1",
     "next": "^15.0.0-canary.28",
+    "next-with-cache-handler-v2": "npm:next@15.3.0-canary.13",
     "os": "^0.1.2",
     "outdent": "^0.8.0",
     "p-limit": "^5.0.0",
@@ -89,13 +90,18 @@
     "uuid": "^10.0.0",
     "vitest": "^3.0.0"
   },
+  "overrides": {
+    "react": "19.0.0-rc.0",
+    "react-dom": "19.0.0-rc.0"
+  },
   "clean-package": {
     "indent": 2,
     "remove": [
       "clean-package",
       "dependencies",
       "devDependencies",
-      "scripts"
+      "scripts",
+      "overrides"
     ]
   }
 }

package.json

@@ -16,10 +16,11 @@ import { join as posixJoin, sep as posixSep } from 'node:path/posix'
 import { trace } from '@opentelemetry/api'
 import { wrapTracer } from '@opentelemetry/api/experimental'
 import glob from 'fast-glob'
-import { prerelease, lt as semverLowerThan, lte as semverLowerThanOrEqual } from 'semver'
+import { prerelease, satisfies, lt as semverLowerThan, lte as semverLowerThanOrEqual } from 'semver'
 
-import { RUN_CONFIG } from '../../run/constants.js'
-import { PluginContext } from '../plugin-context.js'
+import type { RunConfig } from '../../run/config.js'
+import { RUN_CONFIG_FILE } from '../../run/constants.js'
+import type { PluginContext, RequiredServerFilesManifest } from '../plugin-context.js'
 
 const tracer = wrapTracer(trace.getTracer('Next runtime'))
 
@@ -54,7 +55,9 @@ export const copyNextServerCode = async (ctx: PluginContext): Promise<void> => {
         throw error
       }
     }
-    const reqServerFiles = JSON.parse(await readFile(reqServerFilesPath, 'utf-8'))
+    const reqServerFiles = JSON.parse(
+      await readFile(reqServerFilesPath, 'utf-8'),
+    ) as RequiredServerFilesManifest
 
     // if the resolved dist folder does not match the distDir of the required-server-files.json
     // this means the path got altered by a plugin like nx and contained ../../ parts so we have to reset it
@@ -73,8 +76,17 @@ export const copyNextServerCode = async (ctx: PluginContext): Promise<void> => {
     // write our run-config.json to the root dir so that we can easily get the runtime config of the required-server-files.json
     // without the need to know about the monorepo or distDir configuration upfront.
     await writeFile(
-      join(ctx.serverHandlerDir, RUN_CONFIG),
-      JSON.stringify(reqServerFiles.config),
+      join(ctx.serverHandlerDir, RUN_CONFIG_FILE),
+      JSON.stringify({
+        nextConfig: reqServerFiles.config,
+        // only enable setting up 'use cache' handler when Next.js supports CacheHandlerV2 as we don't have V1 compatible implementation
+        // see https://github.com/vercel/next.js/pull/76687 first released in v15.3.0-canary.13
+        enableUseCacheHandler: ctx.nextVersion
+          ? satisfies(ctx.nextVersion, '>=15.3.0-canary.13', {
+              includePrerelease: true,
+            })
+          : false,
+      } satisfies RunConfig),
       'utf-8',
     )
 
@@ -336,9 +348,11 @@ const replaceMiddlewareManifest = async (sourcePath: string, destPath: string) =
 }
 
 export const verifyHandlerDirStructure = async (ctx: PluginContext) => {
-  const runConfig = JSON.parse(await readFile(join(ctx.serverHandlerDir, RUN_CONFIG), 'utf-8'))
+  const { nextConfig } = JSON.parse(
+    await readFile(join(ctx.serverHandlerDir, RUN_CONFIG_FILE), 'utf-8'),
+  ) as RunConfig
 
-  const expectedBuildIDPath = join(ctx.serverHandlerDir, runConfig.distDir, 'BUILD_ID')
+  const expectedBuildIDPath = join(ctx.serverHandlerDir, nextConfig.distDir, 'BUILD_ID')
   if (!existsSync(expectedBuildIDPath)) {
     ctx.failBuild(
       `Failed creating server handler. BUILD_ID file not found at expected location "${expectedBuildIDPath}".`,

src/build/content/server.ts

@@ -4,14 +4,19 @@ import { join, resolve } from 'node:path'
 
 import type { NextConfigComplete } from 'next/dist/server/config-shared.js'
 
-import { PLUGIN_DIR, RUN_CONFIG } from './constants.js'
+import { PLUGIN_DIR, RUN_CONFIG_FILE } from './constants.js'
 import { setInMemoryCacheMaxSizeFromNextConfig } from './storage/storage.cjs'
 
+export type RunConfig = {
+  nextConfig: NextConfigComplete
+  enableUseCacheHandler: boolean
+}
+
 /**
  * Get Next.js config from the build output
  */
 export const getRunConfig = async () => {
-  return JSON.parse(await readFile(resolve(PLUGIN_DIR, RUN_CONFIG), 'utf-8'))
+  return JSON.parse(await readFile(resolve(PLUGIN_DIR, RUN_CONFIG_FILE), 'utf-8')) as RunConfig
 }
 
 type NextConfigForMultipleVersions = NextConfigComplete & {

src/run/config.ts

@@ -4,4 +4,4 @@ import { fileURLToPath } from 'node:url'
 export const MODULE_DIR = fileURLToPath(new URL('.', import.meta.url))
 export const PLUGIN_DIR = resolve(`${MODULE_DIR}../../..`)
 // a file where we store the required-server-files config object in to access during runtime
-export const RUN_CONFIG = 'run-config.json'
+export const RUN_CONFIG_FILE = 'run-config.json'

src/run/constants.ts

@@ -3,9 +3,9 @@ import type { OutgoingHttpHeaders } from 'http'
 import { ComputeJsOutgoingMessage, toComputeResponse, toReqRes } from '@fastly/http-compute-js'
 import type { Context } from '@netlify/functions'
 import { Span } from '@opentelemetry/api'
-import type { NextConfigComplete } from 'next/dist/server/config-shared.js'
 import type { WorkerRequestHandler } from 'next/dist/server/lib/types.js'
 
+import { getRunConfig, setRunConfig } from '../config.js'
 import {
   adjustDateHeader,
   setCacheControlHeaders,
@@ -18,15 +18,22 @@ import { setFetchBeforeNextPatchedIt } from '../storage/storage.cjs'
 
 import { getLogger, type RequestContext } from './request-context.cjs'
 import { getTracer, recordWarning } from './tracer.cjs'
+import { configureUseCacheHandlers } from './use-cache-handler.js'
 import { setupWaitUntil } from './wait-until.cjs'
-
+// make use of global fetch before Next.js applies any patching
 setFetchBeforeNextPatchedIt(globalThis.fetch)
+// configure globals that Next.js make use of before we start importing any Next.js code
+// as some globals are consumed at import time
+const { nextConfig, enableUseCacheHandler } = await getRunConfig()
+if (enableUseCacheHandler) {
+  configureUseCacheHandlers()
+}
+setRunConfig(nextConfig)
+setupWaitUntil()
 
 const nextImportPromise = import('../next.cjs')
 
-setupWaitUntil()
-
-let nextHandler: WorkerRequestHandler, nextConfig: NextConfigComplete
+let nextHandler: WorkerRequestHandler
 
 /**
  * When Next.js proxies requests externally, it writes the response back as-is.
@@ -61,11 +68,6 @@ export default async (
 
   if (!nextHandler) {
     await tracer.withActiveSpan('initialize next server', async () => {
-      // set the server config
-      const { getRunConfig, setRunConfig } = await import('../config.js')
-      nextConfig = await getRunConfig()
-      setRunConfig(nextConfig)
-
       const { getMockedRequestHandler } = await nextImportPromise
       const url = new URL(request.url)
 

src/run/handlers/server.ts

@@ -25,6 +25,27 @@ async function getTagRevalidatedAt(
   return tagManifest.revalidatedAt
 }
 
+/**
+ * Get the most recent revalidation timestamp for a list of tags
+ */
+export async function getMostRecentTagRevalidationTimestamp(tags: string[]) {
+  if (tags.length === 0) {
+    return 0
+  }
+
+  const cacheStore = getMemoizedKeyValueStoreBackedByRegionalBlobStore({ consistency: 'strong' })
+
+  const timestampsOrNulls = await Promise.all(
+    tags.map((tag) => getTagRevalidatedAt(tag, cacheStore)),
+  )
+
+  const timestamps = timestampsOrNulls.filter((timestamp) => timestamp !== null)
+  if (timestamps.length === 0) {
+    return 0
+  }
+  return Math.max(...timestamps)
+}
+
 /**
  * Check if any of the tags were invalidated since the given timestamp
  */