fix: conditionally enable use cache handler based on next version

Author: pieh

src/build/content/server.ts

@@ -16,10 +16,12 @@ 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 type { NextConfigComplete } from 'next/dist/server/config-shared.js'
 import { prerelease, 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'))
 
@@ -32,8 +34,8 @@ function isError(error: unknown): error is NodeJS.ErrnoException {
 /**
  * Copy App/Pages Router Javascript needed by the server handler
  */
-export const copyNextServerCode = async (ctx: PluginContext): Promise<void> => {
-  await tracer.withActiveSpan('copyNextServerCode', async () => {
+export const copyNextServerCode = async (ctx: PluginContext): Promise<NextConfigComplete> => {
+  return await tracer.withActiveSpan('copyNextServerCode', async () => {
     // update the dist directory inside the required-server-files.json to work with
     // nx monorepos and other setups where the dist directory is modified
     const reqServerFilesPath = join(
@@ -54,7 +56,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
@@ -70,13 +74,6 @@ export const copyNextServerCode = async (ctx: PluginContext): Promise<void> => {
 
     // ensure the directory exists before writing to it
     await mkdir(ctx.serverHandlerDir, { recursive: true })
-    // 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),
-      'utf-8',
-    )
 
     const srcDir = join(ctx.standaloneDir, ctx.nextDistDir)
     // if the distDir got resolved and altered use the nextDistDir instead
@@ -114,6 +111,8 @@ export const copyNextServerCode = async (ctx: PluginContext): Promise<void> => {
         await cp(srcPath, destPath, { recursive: true, force: true })
       }),
     )
+
+    return reqServerFiles.config
   })
 }
 
@@ -336,9 +335,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/functions/server.ts

@@ -5,13 +5,17 @@ import { join as posixJoin } from 'node:path/posix'
 import { trace } from '@opentelemetry/api'
 import { wrapTracer } from '@opentelemetry/api/experimental'
 import { glob } from 'fast-glob'
+import type { NextConfigComplete } from 'next/dist/server/config-shared.js'
+import { satisfies } from 'semver'
 
+import type { RunConfig } from '../../run/config.js'
+import { RUN_CONFIG_FILE } from '../../run/constants.js'
 import {
   copyNextDependencies,
   copyNextServerCode,
   verifyHandlerDirStructure,
 } from '../content/server.js'
-import { PluginContext, SERVER_HANDLER_NAME } from '../plugin-context.js'
+import { type PluginContext, SERVER_HANDLER_NAME } from '../plugin-context.js'
 
 const tracer = wrapTracer(trace.getTracer('Next runtime'))
 
@@ -129,6 +133,25 @@ const writeHandlerFile = async (ctx: PluginContext) => {
   await writeFile(join(ctx.serverHandlerRootDir, `${SERVER_HANDLER_NAME}.mjs`), handler)
 }
 
+const writeRunConfig = async (ctx: PluginContext, standaloneNextConfig: NextConfigComplete) => {
+  // 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_FILE),
+    JSON.stringify({
+      nextConfig: standaloneNextConfig,
+      // 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',
+  )
+}
+
 export const clearStaleServerHandlers = async (ctx: PluginContext) => {
   await rm(ctx.serverFunctionsDir, { recursive: true, force: true })
 }
@@ -140,11 +163,12 @@ export const createServerHandler = async (ctx: PluginContext) => {
   await tracer.withActiveSpan('createServerHandler', async () => {
     await mkdir(join(ctx.serverHandlerRuntimeModulesDir), { recursive: true })
 
-    await copyNextServerCode(ctx)
+    const standaloneNextConfig = await copyNextServerCode(ctx)
     await copyNextDependencies(ctx)
     await copyHandlerDependencies(ctx)
     await writeHandlerManifest(ctx)
     await writeHandlerFile(ctx)
+    await writeRunConfig(ctx, standaloneNextConfig)
 
     await verifyHandlerDirStructure(ctx)
   })

src/run/config.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/constants.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/handlers/server.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,
@@ -20,20 +20,20 @@ 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 some globals that Next.js make use of before we start importing any Next.js code
+// configure globals that Next.js make use of before we start importing any Next.js code
 // as some globals are consumed at import time
-// TODO: only call this if Next.js version is using 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 so we should not run tests on older next versions
-configureUseCacheHandlers()
+const { nextConfig, enableUseCacheHandler } = await getRunConfig()
+if (enableUseCacheHandler) {
+  configureUseCacheHandlers()
+}
+setRunConfig(nextConfig)
 setupWaitUntil()
 
 const nextImportPromise = import('../next.cjs')
 
-let nextHandler: WorkerRequestHandler, nextConfig: NextConfigComplete
+let nextHandler: WorkerRequestHandler
 
 /**
  * When Next.js proxies requests externally, it writes the response back as-is.
@@ -68,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)