Turbopack: improve errors/warnings for turbopack messages (#84552)

### What?

* make the turbopack error not a really long line, which is annoying in the deployment build log

 * Show a `(invalid experimental key)` info in the list of experimental options when they are not supported.

Author: sokra

packages/next/src/lib/turbopack-warning.ts

@@ -152,15 +152,20 @@ export async function validateTurboNextConfig({
   if (process.env.TURBOPACK === 'auto' && hasWebpackConfig && !hasTurboConfig) {
     const configFile = rawNextConfig.configFileName ?? 'your Next config file'
     Log.error(
-      `ERROR: This build is using Turbopack, with a \`webpack\` config and no \`turbopack\` config. This may be a mistake.
+      `ERROR: This build is using Turbopack, with a \`webpack\` config and no \`turbopack\` config.
+   This may be a mistake.
 
-  As of Next.js 16 turbopack is enabled by default and custom webpack configurations may need to be migrated to Turbopack.
+   As of Next.js 16 Turbopack is enabled by default and
+   custom webpack configurations may need to be migrated to Turbopack.
 
-  NOTE: your \`webpack\` config may have been added by a configuration plugin.
+   NOTE: your \`webpack\` config may have been added by a configuration plugin.
 
-  To configure Turbopack, see https://nextjs.org/docs/app/api-reference/next-config-js/turbopack
+   To configure Turbopack, see https://nextjs.org/docs/app/api-reference/next-config-js/turbopack
 
-  TIP: Many applications work fine under Turbopack with no configuration, if that is the case for you, you can silence this error by passing the \`--turbopack\` or \`--webpack\` flag explicitly or simply setting an empty turbopack config in ${configFile} (e.g. \`turbopack: {}\`).`
+   TIP: Many applications work fine under Turbopack with no configuration,
+   if that is the case for you, you can silence this error by passing the
+   \`--turbopack\` or \`--webpack\` flag explicitly or simply setting an 
+   empty turbopack config in ${configFile} (e.g. \`turbopack: {}\`).`
     )
 
     process.exit(1)

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

@@ -57,6 +57,18 @@ function normalizeNextConfigZodErrors(
         // We exit the build when encountering an error in the images config
         shouldExit = true
       }
+      if (
+        issue.code === 'unrecognized_keys' &&
+        issue.path[0] === 'experimental' &&
+        message.includes('turbopackPersistentCaching')
+      ) {
+        // We exit the build when encountering an error in the turbopackPersistentCaching config
+        shouldExit = true
+        message +=
+          "\nUse 'experimental.turbopackPersistentCachingForDev' instead."
+        message +=
+          '\nLearn more: https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopackPersistentCaching'
+      }
 
       return message
     }),
@@ -1974,7 +1986,7 @@ async function validateConfigSchema(
     )
     // ident list item
     for (const error of errorMessages) {
-      messages.push(`    ${error}`)
+      messages.push(`    ${error.split('\n').join('\n    ')}`)
     }
 
     // error message footer

packages/next/src/server/config.ts

@@ -1,11 +1,12 @@
 import { loadEnvConfig } from '@next/env'
 import * as Log from '../../build/output/log'
-import { bold, purple } from '../../lib/picocolors'
+import { bold, purple, strikethrough } from '../../lib/picocolors'
 import {
   PHASE_DEVELOPMENT_SERVER,
   PHASE_PRODUCTION_BUILD,
 } from '../../shared/lib/constants'
 import loadConfig, { type ConfiguredExperimentalFeature } from '../config'
+import { experimentalSchema } from '../config-schema'
 
 export function logStartInfo({
   networkUrl,
@@ -47,21 +48,31 @@ export function logStartInfo({
   if (experimentalFeatures?.length) {
     Log.bootstrap(`- Experiments (use with caution):`)
     for (const exp of experimentalFeatures) {
-      const symbol =
-        typeof exp.value === 'boolean'
-          ? exp.value === true
-            ? bold('✓')
-            : bold('⨯')
-          : '·'
+      const isValid = Object.prototype.hasOwnProperty.call(
+        experimentalSchema,
+        exp.key
+      )
+      if (isValid) {
+        const symbol =
+          typeof exp.value === 'boolean'
+            ? exp.value === true
+              ? bold('✓')
+              : bold('⨯')
+            : '·'
 
-      const suffix =
-        typeof exp.value === 'number' || typeof exp.value === 'string'
-          ? `: ${JSON.stringify(exp.value)}`
-          : ''
+        const suffix =
+          typeof exp.value === 'number' || typeof exp.value === 'string'
+            ? `: ${JSON.stringify(exp.value)}`
+            : ''
 
-      const reason = exp.reason ? ` (${exp.reason})` : ''
+        const reason = exp.reason ? ` (${exp.reason})` : ''
 
-      Log.bootstrap(`  ${symbol} ${exp.key}${suffix}${reason}`)
+        Log.bootstrap(`  ${symbol} ${exp.key}${suffix}${reason}`)
+      } else {
+        Log.bootstrap(
+          `  ? ${strikethrough(exp.key)} (invalid experimental key)`
+        )
+      }
     }
   }
 

packages/next/src/server/lib/app-info-log.ts

@@ -1,8 +1,7 @@
 /* eslint-disable jest/no-standalone-expect */
 import { nextTestSetup } from 'e2e-utils'
 
-const WARNING_MESSAGE =
-  'ERROR: This build is using Turbopack, with a `webpack` config and no `turbopack` config. This may be a mistake'
+const WARNING_MESSAGE = `ERROR: This build is using Turbopack, with a \`webpack\` config and no \`turbopack\` config.`
 
 const itif = (condition: boolean) => (condition ? it : it.skip)
 

test/e2e/config-turbopack/index.test.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react'
+export default function Root({ children }: { children: ReactNode }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}

test/e2e/persistent-caching-migration/app/layout.tsx

@@ -0,0 +1,7 @@
+export default function Page() {
+  return (
+    <>
+      <p>hello world</p>
+    </>
+  )
+}

test/e2e/persistent-caching-migration/app/page.tsx

@@ -0,0 +1,10 @@
+/**
+ * @type {import('next').NextConfig}
+ */
+const nextConfig = {
+  experimental: {
+    turbopackPersistentCaching: true,
+  },
+}
+
+module.exports = nextConfig

test/e2e/persistent-caching-migration/next.config.js

@@ -0,0 +1,7 @@
+export default function Page() {
+  return (
+    <>
+      <p>hello world</p>
+    </>
+  )
+}

test/e2e/persistent-caching-migration/pages/pages.tsx

@@ -0,0 +1,35 @@
+import { nextTestSetup } from 'e2e-utils'
+
+describe('persistent-caching-migration', () => {
+  const { skipped, next, isTurbopack, isNextStart } = nextTestSetup({
+    files: __dirname,
+    skipDeployment: true,
+    skipStart: true,
+  })
+
+  if (skipped) {
+    return
+  }
+
+  if (!isTurbopack) {
+    it.skip('only for turbopack', () => {})
+    return
+  }
+
+  if (isNextStart) {
+    it('error on old option', async () => {
+      let { exitCode, cliOutput } = await next.build()
+      expect(exitCode).toBe(1)
+      expect(cliOutput).toContain(
+        "Use 'experimental.turbopackPersistentCachingForDev' instead."
+      )
+    })
+  } else {
+    it('success on new option', async () => {
+      await expect(next.start()).toReject()
+      expect(next.cliOutput).toContain(
+        "Use 'experimental.turbopackPersistentCachingForDev' instead."
+      )
+    })
+  }
+})