fix: update cache handler to accomodate changes in next@canary (#2480)

* fix: update cache handler to accomodate changes in next@canary

* initial implementation for creating cache entry blobs from prerendered content for APP_PAGE

* chore: mark config.experimental.incrementalCacheHandlerPath as TS ignored, because it no longer exist in newest major, but we still have to set it for older next versions

* fix: handle APP_PAGE cache kind when checking tag staleness

* fix: handle prerendered ppr rsc

* do Next.js version verification earlier and make it easy to grab the version after build command finished

* decide wether to use APP_PAGE or PAGE kind based on actual next version

Author: pieh

package-lock.json

@@ -79,7 +79,7 @@
     "memfs": "^4.9.2",
     "mock-require": "^3.0.3",
     "msw": "^2.0.7",
-    "next": "^14.0.4",
+    "next": "^15.0.0-canary.28",
     "os": "^0.1.2",
     "outdent": "^0.8.0",
     "p-limit": "^5.0.0",

package.json

@@ -6,10 +6,12 @@ import { trace } from '@opentelemetry/api'
 import { wrapTracer } from '@opentelemetry/api/experimental'
 import { glob } from 'fast-glob'
 import pLimit from 'p-limit'
+import { satisfies } from 'semver'
 
 import { encodeBlobKey } from '../../shared/blobkey.js'
 import type {
   CachedFetchValue,
+  NetlifyCachedAppPageValue,
   NetlifyCachedPageValue,
   NetlifyCachedRouteValue,
   NetlifyCacheHandlerValue,
@@ -46,13 +48,29 @@ const buildPagesCacheValue = async (path: string): Promise<NetlifyCachedPageValu
   kind: 'PAGE',
   html: await readFile(`${path}.html`, 'utf-8'),
   pageData: JSON.parse(await readFile(`${path}.json`, 'utf-8')),
-  postponed: undefined,
   headers: undefined,
   status: undefined,
 })
 
-const buildAppCacheValue = async (path: string): Promise<NetlifyCachedPageValue> => {
+const buildAppCacheValue = async (
+  path: string,
+  shouldUseAppPageKind: boolean,
+): Promise<NetlifyCachedAppPageValue | NetlifyCachedPageValue> => {
   const meta = JSON.parse(await readFile(`${path}.meta`, 'utf-8'))
+  const html = await readFile(`${path}.html`, 'utf-8')
+
+  // supporting both old and new cache kind for App Router pages - https://github.com/vercel/next.js/pull/65988
+  if (shouldUseAppPageKind) {
+    return {
+      kind: 'APP_PAGE',
+      html,
+      rscData: await readFile(`${path}.rsc`, 'base64').catch(() =>
+        readFile(`${path}.prefetch.rsc`, 'base64'),
+      ),
+      ...meta,
+    }
+  }
+
   const rsc = await readFile(`${path}.rsc`, 'utf-8').catch(() =>
     readFile(`${path}.prefetch.rsc`, 'utf-8'),
   )
@@ -66,10 +84,9 @@ const buildAppCacheValue = async (path: string): Promise<NetlifyCachedPageValue>
   ) {
     meta.status = 404
   }
-
   return {
     kind: 'PAGE',
-    html: await readFile(`${path}.html`, 'utf-8'),
+    html,
     pageData: rsc,
     ...meta,
   }
@@ -103,6 +120,18 @@ export const copyPrerenderedContent = async (ctx: PluginContext): Promise<void>
 
       const limitConcurrentPrerenderContentHandling = pLimit(10)
 
+      // https://github.com/vercel/next.js/pull/65988 introduced Cache kind specific to pages in App Router (`APP_PAGE`).
+      // Before this change there was common kind for both Pages router and App router pages
+      // so we check Next.js version to decide how to generate cache values for App Router pages.
+      // Note: at time of writing this code, released 15@rc uses old kind for App Router pages, while [email protected] and newer canaries use new kind.
+      // Looking at 15@rc release branch it was merging `canary` branch in, so the version constraint assumes that future 15@rc (and 15@latest) versions
+      // will use new kind for App Router pages.
+      const shouldUseAppPageKind = ctx.nextVersion
+        ? satisfies(ctx.nextVersion, '>=15.0.0-canary.13 <15.0.0-d || >15.0.0-rc.0', {
+            includePrerelease: true,
+          })
+        : false
+
       await Promise.all(
         Object.entries(manifest.routes).map(
           ([route, meta]): Promise<void> =>
@@ -125,7 +154,10 @@ export const copyPrerenderedContent = async (ctx: PluginContext): Promise<void>
                   value = await buildPagesCacheValue(join(ctx.publishDir, 'server/pages', key))
                   break
                 case meta.dataRoute?.endsWith('.rsc'):
-                  value = await buildAppCacheValue(join(ctx.publishDir, 'server/app', key))
+                  value = await buildAppCacheValue(
+                    join(ctx.publishDir, 'server/app', key),
+                    shouldUseAppPageKind,
+                  )
                   break
                 case meta.dataRoute === null:
                   value = await buildRouteCacheValue(
@@ -147,7 +179,10 @@ export const copyPrerenderedContent = async (ctx: PluginContext): Promise<void>
       if (existsSync(join(ctx.publishDir, `server/app/_not-found.html`))) {
         const lastModified = Date.now()
         const key = '/404'
-        const value = await buildAppCacheValue(join(ctx.publishDir, 'server/app/_not-found'))
+        const value = await buildAppCacheValue(
+          join(ctx.publishDir, 'server/app/_not-found'),
+          shouldUseAppPageKind,
+        )
         await writeCacheEntry(key, value, lastModified, ctx)
       }
     } catch (error) {

src/build/content/prerendered.ts

@@ -20,7 +20,6 @@ import { prerelease, lt as semverLowerThan, lte as semverLowerThanOrEqual } from
 
 import { RUN_CONFIG } from '../../run/constants.js'
 import { PluginContext } from '../plugin-context.js'
-import { verifyNextVersion } from '../verification.js'
 
 const tracer = wrapTracer(trace.getTracer('Next runtime'))
 
@@ -292,26 +291,13 @@ export const copyNextDependencies = async (ctx: PluginContext): Promise<void> =>
 
     await Promise.all(promises)
 
-    // detect if it might lead to a runtime issue and throw an error upfront on build time instead of silently failing during runtime
     const serverHandlerRequire = createRequire(posixJoin(ctx.serverHandlerDir, ':internal:'))
 
-    let nextVersion: string | undefined
-    try {
-      const { version } = serverHandlerRequire('next/package.json')
-      if (version) {
-        nextVersion = version as string
-      }
-    } catch {
-      // failed to resolve package.json - currently this is resolvable in all known next versions, but if next implements
-      // exports map it still might be a problem in the future, so we are not breaking here
-    }
-
-    if (nextVersion) {
-      verifyNextVersion(ctx, nextVersion)
-
-      await patchNextModules(ctx, nextVersion, serverHandlerRequire.resolve)
+    if (ctx.nextVersion) {
+      await patchNextModules(ctx, ctx.nextVersion, serverHandlerRequire.resolve)
     }
 
+    // detect if it might lead to a runtime issue and throw an error upfront on build time instead of silently failing during runtime
     try {
       const nextEntryAbsolutePath = serverHandlerRequire.resolve('next')
       const nextRequire = createRequire(nextEntryAbsolutePath)

src/build/content/server.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
 import { join, relative, resolve } from 'node:path'
+import { join as posixJoin } from 'node:path/posix'
 import { fileURLToPath } from 'node:url'
 
 import type {
@@ -313,6 +315,25 @@ export class PluginContext {
     return JSON.parse(await readFile(join(this.publishDir, 'routes-manifest.json'), 'utf-8'))
   }
 
+  #nextVersion: string | null | undefined = undefined
+
+  /**
+   * Get Next.js version that was used to build the site
+   */
+  get nextVersion(): string | null {
+    if (this.#nextVersion === undefined) {
+      try {
+        const serverHandlerRequire = createRequire(posixJoin(this.standaloneRootDir, ':internal:'))
+        const { version } = serverHandlerRequire('next/package.json')
+        this.#nextVersion = version as string
+      } catch {
+        this.#nextVersion = null
+      }
+    }
+
+    return this.#nextVersion
+  }
+
   /** Fails a build with a message and an optional error */
   failBuild(message: string, error?: unknown): never {
     return this.utils.build.failBuild(message, error instanceof Error ? { error } : undefined)

src/build/plugin-context.ts

@@ -47,6 +47,15 @@ export function verifyPublishDir(ctx: PluginContext) {
         `Your publish directory does not contain expected Next.js build output. Please make sure you are using Next.js version (${SUPPORTED_NEXT_VERSIONS})`,
       )
     }
+
+    if (
+      ctx.nextVersion &&
+      !satisfies(ctx.nextVersion, SUPPORTED_NEXT_VERSIONS, { includePrerelease: true })
+    ) {
+      ctx.failBuild(
+        `@netlify/plugin-next@5 requires Next.js version ${SUPPORTED_NEXT_VERSIONS}, but found ${ctx.nextVersion}. Please upgrade your project's Next.js version.`,
+      )
+    }
   }
   if (ctx.buildConfig.output === 'export') {
     if (!ctx.exportDetail?.success) {
@@ -60,14 +69,6 @@ export function verifyPublishDir(ctx: PluginContext) {
   }
 }
 
-export function verifyNextVersion(ctx: PluginContext, nextVersion: string): void | never {
-  if (!satisfies(nextVersion, SUPPORTED_NEXT_VERSIONS, { includePrerelease: true })) {
-    ctx.failBuild(
-      `@netlify/plugin-next@5 requires Next.js version ${SUPPORTED_NEXT_VERSIONS}, but found ${nextVersion}. Please upgrade your project's Next.js version.`,
-    )
-  }
-}
-
 export async function verifyNoAdvancedAPIRoutes(ctx: PluginContext) {
   const apiRoutesConfigs = await getAPIRoutesConfigs(ctx)
 

src/build/verification.ts

@@ -25,6 +25,8 @@ export const setRunConfig = (config: NextConfigComplete) => {
   // set the path to the cache handler
   config.experimental = {
     ...config.experimental,
+    // @ts-expect-error incrementalCacheHandlerPath was removed from config type
+    // but we still need to set it for older Next.js versions
     incrementalCacheHandlerPath: cacheHandler,
   }
 

src/run/config.ts

@@ -10,8 +10,6 @@ import { purgeCache } from '@netlify/functions'
 import { type Span } from '@opentelemetry/api'
 import type { PrerenderManifest } from 'next/dist/build/index.js'
 import { NEXT_CACHE_TAGS_HEADER } from 'next/dist/lib/constants.js'
-import { loadManifest } from 'next/dist/server/load-manifest.js'
-import { normalizePagePath } from 'next/dist/shared/lib/page-path/normalize-page-path.js'
 
 import type {
   CacheHandler,
@@ -111,23 +109,41 @@ export class NetlifyCacheHandler implements CacheHandler {
     return restOfRouteValue
   }
 
-  private injectEntryToPrerenderManifest(
+  private async injectEntryToPrerenderManifest(
     key: string,
     revalidate: NetlifyCachedPageValue['revalidate'],
   ) {
     if (this.options.serverDistDir && (typeof revalidate === 'number' || revalidate === false)) {
-      const prerenderManifest = loadManifest(
-        join(this.options.serverDistDir, '..', 'prerender-manifest.json'),
-      ) as PrerenderManifest
-
-      prerenderManifest.routes[key] = {
-        experimentalPPR: undefined,
-        dataRoute: posixJoin('/_next/data', `${normalizePagePath(key)}.json`),
-        srcRoute: null, // FIXME: provide actual source route, however, when dynamically appending it doesn't really matter
-        initialRevalidateSeconds: revalidate,
-        // Pages routes do not have a prefetch data route.
-        prefetchDataRoute: undefined,
-      }
+      try {
+        const { loadManifest } = await import('next/dist/server/load-manifest.js')
+        const prerenderManifest = loadManifest(
+          join(this.options.serverDistDir, '..', 'prerender-manifest.json'),
+        ) as PrerenderManifest
+
+        try {
+          const { normalizePagePath } = await import(
+            'next/dist/shared/lib/page-path/normalize-page-path.js'
+          )
+
+          prerenderManifest.routes[key] = {
+            experimentalPPR: undefined,
+            dataRoute: posixJoin('/_next/data', `${normalizePagePath(key)}.json`),
+            srcRoute: null, // FIXME: provide actual source route, however, when dynamically appending it doesn't really matter
+            initialRevalidateSeconds: revalidate,
+            // Pages routes do not have a prefetch data route.
+            prefetchDataRoute: undefined,
+          }
+        } catch {
+          // depending on Next.js version - prerender manifest might not be mutable
+          // https://github.com/vercel/next.js/pull/64313
+          // if it's not mutable we will try to use SharedRevalidateTimings ( https://github.com/vercel/next.js/pull/64370) instead
+          const { SharedRevalidateTimings } = await import(
+            'next/dist/server/lib/incremental-cache/shared-revalidate-timings.js'
+          )
+          const sharedRevalidateTimings = new SharedRevalidateTimings(prerenderManifest)
+          sharedRevalidateTimings.set(key, revalidate)
+        }
+      } catch {}
     }
   }
 
@@ -178,7 +194,7 @@ export class NetlifyCacheHandler implements CacheHandler {
             lastModified: blob.lastModified,
             value: {
               ...valueWithoutRevalidate,
-              body: Buffer.from(valueWithoutRevalidate.body as unknown as string, 'base64'),
+              body: Buffer.from(valueWithoutRevalidate.body, 'base64'),
             },
           }
         }
@@ -187,13 +203,28 @@ export class NetlifyCacheHandler implements CacheHandler {
 
           const { revalidate, ...restOfPageValue } = blob.value
 
-          this.injectEntryToPrerenderManifest(key, revalidate)
+          await this.injectEntryToPrerenderManifest(key, revalidate)
 
           return {
             lastModified: blob.lastModified,
             value: restOfPageValue,
           }
         }
+        case 'APP_PAGE': {
+          span.addEvent('APP_PAGE', { lastModified: blob.lastModified })
+
+          const { revalidate, rscData, ...restOfPageValue } = blob.value
+
+          await this.injectEntryToPrerenderManifest(key, revalidate)
+
+          return {
+            lastModified: blob.lastModified,
+            value: {
+              ...restOfPageValue,
+              rscData: rscData ? Buffer.from(rscData, 'base64') : undefined,
+            },
+          }
+        }
         default:
           span.recordException(new Error(`Unknown cache entry kind: ${blob.value?.kind}`))
       }
@@ -220,6 +251,14 @@ export class NetlifyCacheHandler implements CacheHandler {
       }
     }
 
+    if (data?.kind === 'APP_PAGE') {
+      return {
+        ...data,
+        revalidate: context.revalidate,
+        rscData: data.rscData?.toString('base64'),
+      }
+    }
+
     return data
   }
 
@@ -299,7 +338,11 @@ export class NetlifyCacheHandler implements CacheHandler {
 
     if (cacheEntry.value?.kind === 'FETCH') {
       cacheTags = [...tags, ...softTags]
-    } else if (cacheEntry.value?.kind === 'PAGE' || cacheEntry.value?.kind === 'ROUTE') {
+    } else if (
+      cacheEntry.value?.kind === 'PAGE' ||
+      cacheEntry.value?.kind === 'APP_PAGE' ||
+      cacheEntry.value?.kind === 'ROUTE'
+    ) {
       cacheTags = (cacheEntry.value.headers?.[NEXT_CACHE_TAGS_HEADER] as string)?.split(',') || []
     } else {
       return false

src/run/handlers/cache.cts

@@ -4,6 +4,7 @@ import type {
 } from 'next/dist/server/lib/incremental-cache/index.js'
 import type {
   CachedRouteValue,
+  IncrementalCachedAppPageValue,
   IncrementalCacheValue,
 } from 'next/dist/server/response-cache/types.js'
 
@@ -21,6 +22,12 @@ export type NetlifyCachedRouteValue = Omit<CachedRouteValue, 'body'> & {
   revalidate: Parameters<IncrementalCache['set']>[2]['revalidate']
 }
 
+export type NetlifyCachedAppPageValue = Omit<IncrementalCachedAppPageValue, 'rscData'> & {
+  // Next.js stores rscData as buffer, while we store it as base64 encoded string
+  rscData: string | undefined
+  revalidate?: Parameters<IncrementalCache['set']>[2]['revalidate']
+}
+
 type CachedPageValue = Extract<IncrementalCacheValue, { kind: 'PAGE' }>
 
 export type NetlifyCachedPageValue = CachedPageValue & {
@@ -30,15 +37,22 @@ export type NetlifyCachedPageValue = CachedPageValue & {
 export type CachedFetchValue = Extract<IncrementalCacheValue, { kind: 'FETCH' }>
 
 export type NetlifyIncrementalCacheValue =
-  | Exclude<IncrementalCacheValue, CachedRouteValue | CachedPageValue>
+  | Exclude<
+      IncrementalCacheValue,
+      CachedRouteValue | CachedPageValue | IncrementalCachedAppPageValue
+    >
   | NetlifyCachedRouteValue
   | NetlifyCachedPageValue
+  | NetlifyCachedAppPageValue
 
 type CachedRouteValueToNetlify<T> = T extends CachedRouteValue
   ? NetlifyCachedRouteValue
   : T extends CachedPageValue
     ? NetlifyCachedPageValue
-    : T
+    : T extends IncrementalCachedAppPageValue
+      ? NetlifyCachedAppPageValue
+      : T
+
 type MapCachedRouteValueToNetlify<T> = { [K in keyof T]: CachedRouteValueToNetlify<T[K]> }
 
 export type NetlifyCacheHandlerValue = MapCachedRouteValueToNetlify<CacheHandlerValue>