[Turbopack] add unstable prefix to persistent caching option and forc…

…e to provide an expected level of stability (#71090)

### What?

Rename option to `unstablePersistentCaching` and require to pass a
persistent caching version (currently 1).

We increase the number when making improvements to persistent caching.
Smaller numbers are accepted too, but providing a larger number will
fail the build.

e. g. if we document `experimental.turbo.unstablePersistentCaching: 5`,
this will only work for next version that ship at least persistent
caching with version 5. Older version would be rejected.

packages/next/src/build/index.ts

@@ -188,6 +188,7 @@ import {
   handlePagesErrorRoute,
   formatIssue,
   isRelevantWarning,
+  isPersistentCachingEnabled,
 } from '../server/dev/turbopack-utils'
 import { TurbopackManifestLoader } from '../server/dev/turbopack/manifest-loader'
 import type { Entrypoints } from '../server/dev/turbopack/types'
@@ -1409,7 +1410,7 @@ export default async function build(
             browserslistQuery: supportedBrowsers.join(', '),
           },
           {
-            persistentCaching: config.experimental.turbo?.persistentCaching,
+            persistentCaching: isPersistentCachingEnabled(config),
             memoryLimit: config.experimental.turbo?.memoryLimit,
           }
         )

packages/next/src/server/config-schema.ts

@@ -391,7 +391,9 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
             resolveExtensions: z.array(z.string()).optional(),
             useSwcCss: z.boolean().optional(),
             treeShaking: z.boolean().optional(),
-            persistentCaching: z.boolean().optional(),
+            persistentCaching: z
+              .union([z.number(), z.literal(false)])
+              .optional(),
             memoryLimit: z.number().optional(),
             moduleIdStrategy: z.enum(['named', 'deterministic']).optional(),
           })

packages/next/src/server/config-shared.ts

@@ -156,8 +156,10 @@ export interface ExperimentalTurboOptions {
 
   /**
    * Enable persistent caching for the turbopack dev server and build.
+   * Need to provide the expected level of stability, otherwise it will fail.
+   * Currently stability level: 1
    */
-  persistentCaching?: boolean
+  unstablePersistentCaching?: number | false
 
   /**
    * Enable tree shaking for the turbopack dev server and build.

packages/next/src/server/dev/hot-reloader-turbopack.ts

@@ -60,6 +60,7 @@ import {
   isWellKnownError,
   printNonFatalIssue,
   normalizedPageToTurbopackStructureRoute,
+  isPersistentCachingEnabled,
 } from './turbopack-utils'
 import {
   propagateServerField,
@@ -176,7 +177,7 @@ export async function createHotReloaderTurbopack(
       browserslistQuery: supportedBrowsers.join(', '),
     },
     {
-      persistentCaching: opts.nextConfig.experimental.turbo?.persistentCaching,
+      persistentCaching: isPersistentCachingEnabled(opts.nextConfig),
       memoryLimit: opts.nextConfig.experimental.turbo?.memoryLimit,
     }
   )

packages/next/src/server/dev/turbopack-utils.ts

@@ -1159,3 +1159,15 @@ export function normalizedPageToTurbopackStructureRoute(
   }
   return entrypointKey
 }
+
+export function isPersistentCachingEnabled(
+  config: NextConfigComplete
+): boolean {
+  const unstableValue = config.experimental.turbo?.unstablePersistentCaching
+  if (typeof unstableValue === 'number' && unstableValue > 1) {
+    throw new Error(
+      'Persistent caching in this version of Turbopack is not as stable as expected. Upgrade to a newer version of Turbopack to use this feature with the expected stability.'
+    )
+  }
+  return !!unstableValue
+}