auto-enable clientParamParsing and clientSegmentCache w/ cacheComponents (#84250)

ztanner · web-flow · commit efa1ad49e829 · 2025-09-30T09:59:50.000-07:00
When you try `experimental.cacheComponents`, we should auto-enable the
supporting flags (`clientSegmentCache`, `clientParamParsing`), just like
we were doing with PPR to avoid the need to think about all the
different flags needed to get the best cache components testing
experience. Like before, these flags can be explicitly disabled for any
reason.
diff --git a/packages/next/src/server/config.ts b/packages/next/src/server/config.ts
@@ -1690,59 +1690,68 @@ function enforceExperimentalFeatures(
     }
   }
 
-  // TODO: Remove this once we've made Client Segment Cache the default.
+  // TODO: Remove this once we've made Cache Components the default.
   if (
-    process.env.__NEXT_EXPERIMENTAL_PPR === 'true' &&
+    process.env.__NEXT_EXPERIMENTAL_CACHE_COMPONENTS === 'true' &&
     // We do respect an explicit value in the user config.
-    (config.experimental.clientSegmentCache === undefined ||
-      (isDefaultConfig && !config.experimental.clientSegmentCache))
+    (config.experimental.cacheComponents === undefined ||
+      (isDefaultConfig && !config.experimental.cacheComponents))
   ) {
-    config.experimental.clientSegmentCache = true
+    config.experimental.cacheComponents = true
 
     if (configuredExperimentalFeatures) {
       addConfiguredExperimentalFeature(
         configuredExperimentalFeatures,
-        'clientSegmentCache',
+        'cacheComponents',
         true,
-        'enabled by `__NEXT_EXPERIMENTAL_PPR`'
+        'enabled by `__NEXT_EXPERIMENTAL_CACHE_COMPONENTS`'
       )
     }
   }
 
-  // TODO: Remove this once we've made Client Param Parsing the default.
+  const enabledByPprEnv = process.env.__NEXT_EXPERIMENTAL_PPR === 'true'
+  const enabledByCacheComponents = config.experimental.cacheComponents === true
+
+  // TODO: Remove this once we've made Client Segment Cache the default.
   if (
-    process.env.__NEXT_EXPERIMENTAL_PPR === 'true' &&
+    (enabledByPprEnv || enabledByCacheComponents) &&
     // We do respect an explicit value in the user config.
-    (config.experimental.clientParamParsing === undefined ||
-      (isDefaultConfig && !config.experimental.clientParamParsing))
+    (config.experimental.clientSegmentCache === undefined ||
+      (isDefaultConfig && !config.experimental.clientSegmentCache))
   ) {
-    config.experimental.clientParamParsing = true
+    config.experimental.clientSegmentCache = true
+    const reason = enabledByCacheComponents
+      ? 'enabled by `experimental.cacheComponents`'
+      : 'enabled by `__NEXT_EXPERIMENTAL_PPR`'
 
     if (configuredExperimentalFeatures) {
       addConfiguredExperimentalFeature(
         configuredExperimentalFeatures,
-        'clientParamParsing',
+        'clientSegmentCache',
         true,
-        'enabled by `__NEXT_EXPERIMENTAL_PPR`'
+        reason
       )
     }
   }
 
-  // TODO: Remove this once we've made Cache Components the default.
+  // TODO: Remove this once we've made Client Param Parsing the default.
   if (
-    process.env.__NEXT_EXPERIMENTAL_CACHE_COMPONENTS === 'true' &&
+    (enabledByPprEnv || enabledByCacheComponents) &&
     // We do respect an explicit value in the user config.
-    (config.experimental.cacheComponents === undefined ||
-      (isDefaultConfig && !config.experimental.cacheComponents))
+    (config.experimental.clientParamParsing === undefined ||
+      (isDefaultConfig && !config.experimental.clientParamParsing))
   ) {
-    config.experimental.cacheComponents = true
+    config.experimental.clientParamParsing = true
+    const reason = enabledByCacheComponents
+      ? 'enabled by `experimental.cacheComponents`'
+      : 'enabled by `__NEXT_EXPERIMENTAL_PPR`'
 
     if (configuredExperimentalFeatures) {
       addConfiguredExperimentalFeature(
         configuredExperimentalFeatures,
-        'cacheComponents',
+        'clientParamParsing',
         true,
-        'enabled by `__NEXT_EXPERIMENTAL_CACHE_COMPONENTS`'
+        reason
       )
     }
   }
diff --git a/test/e2e/app-dir/segment-cache/basic/segment-cache-basic.test.ts b/test/e2e/app-dir/segment-cache/basic/segment-cache-basic.test.ts
@@ -93,7 +93,11 @@ describe('segment cache (basic tests)', () => {
     )
   })
 
-  it('navigate to page with lazily-generated (not at build time) static param', async () => {
+  // TODO(client-param-parsing): With `clientParamParsing` enabled, this test is outdated, because
+  // we no longer put the param values in the prefetched RSC response. You'd have to opt into runtime
+  // prefetching for this test to pass until we ship the optimization that would mark this as fully static
+  // if you don't reference any dynamic params in the server components.
+  it.skip('navigate to page with lazily-generated (not at build time) static param', async () => {
     let act: ReturnType<typeof createRouterAct>
     const browser = await next.browser('/lazily-generated-params', {
       beforePageLoad(page) {
diff --git a/test/production/app-dir/build-output-prerender/build-output-prerender.test.ts b/test/production/app-dir/build-output-prerender/build-output-prerender.test.ts
@@ -26,8 +26,8 @@ describe('build-output-prerender', () => {
              "▲ Next.js x.y.z (Turbopack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`experimental.cacheComponents\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
                   ✓ rdcForNavigations (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)"
@@ -37,8 +37,8 @@ describe('build-output-prerender', () => {
              "▲ Next.js x.y.z (webpack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`experimental.cacheComponents\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
                   ✓ rdcForNavigations (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)"
@@ -61,8 +61,8 @@ describe('build-output-prerender', () => {
              "▲ Next.js x.y.z (webpack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`experimental.cacheComponents\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
                   ✓ rdcForNavigations (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)"
@@ -74,6 +74,8 @@ describe('build-output-prerender', () => {
              "▲ Next.js x.y.z (Turbopack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`experimental.cacheComponents\`)
                   ✓ ppr (enabled by \`experimental.cacheComponents\`)
                   ✓ rdcForNavigations (enabled by \`experimental.ppr\`)"
@@ -83,6 +85,8 @@ describe('build-output-prerender', () => {
              "▲ Next.js x.y.z (Rspack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`experimental.cacheComponents\`)
                   ✓ ppr (enabled by \`experimental.cacheComponents\`)
                   ✓ rdcForNavigations (enabled by \`experimental.ppr\`)"
@@ -92,6 +96,8 @@ describe('build-output-prerender', () => {
              "▲ Next.js x.y.z (webpack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`experimental.cacheComponents\`)
                   ✓ ppr (enabled by \`experimental.cacheComponents\`)
                   ✓ rdcForNavigations (enabled by \`experimental.ppr\`)"
@@ -149,8 +155,8 @@ describe('build-output-prerender', () => {
                 ▲ Next.js x.y.z (Turbopack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`--debug-prerender\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
                   ⨯ prerenderEarlyExit (disabled by \`--debug-prerender\`)
@@ -164,8 +170,8 @@ describe('build-output-prerender', () => {
                 ▲ Next.js x.y.z (webpack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`--debug-prerender\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
                   ⨯ prerenderEarlyExit (disabled by \`--debug-prerender\`)
@@ -196,8 +202,8 @@ describe('build-output-prerender', () => {
                 ▲ Next.js x.y.z (webpack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`--debug-prerender\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
                   ⨯ prerenderEarlyExit (disabled by \`--debug-prerender\`)
@@ -213,6 +219,8 @@ describe('build-output-prerender', () => {
                 ▲ Next.js x.y.z (Turbopack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`--debug-prerender\`)
                   ✓ ppr (enabled by \`experimental.cacheComponents\`)
                   ⨯ prerenderEarlyExit (disabled by \`--debug-prerender\`)
@@ -226,6 +234,8 @@ describe('build-output-prerender', () => {
                 ▲ Next.js x.y.z (Rspack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`--debug-prerender\`)
                   ✓ ppr (enabled by \`experimental.cacheComponents\`)
                   ⨯ prerenderEarlyExit (disabled by \`--debug-prerender\`)
@@ -239,6 +249,8 @@ describe('build-output-prerender', () => {
                 ▲ Next.js x.y.z (webpack)
                 - Experiments (use with caution):
                   ✓ cacheComponents
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`--debug-prerender\`)
                   ✓ ppr (enabled by \`experimental.cacheComponents\`)
                   ⨯ prerenderEarlyExit (disabled by \`--debug-prerender\`)
@@ -297,8 +309,8 @@ describe('build-output-prerender', () => {
              "▲ Next.js x.y.z (Turbopack)
                 - Experiments (use with caution):
                   ✓ cacheComponents (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`experimental.cacheComponents\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
                   ✓ rdcForNavigations (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)"
@@ -308,8 +320,8 @@ describe('build-output-prerender', () => {
              "▲ Next.js x.y.z (webpack)
                 - Experiments (use with caution):
                   ✓ cacheComponents (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`experimental.cacheComponents\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
                   ✓ rdcForNavigations (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)"
@@ -370,8 +382,8 @@ describe('build-output-prerender', () => {
                 ▲ Next.js x.y.z (Turbopack)
                 - Experiments (use with caution):
                   ✓ cacheComponents (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`--debug-prerender\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
                   ⨯ prerenderEarlyExit (disabled by \`--debug-prerender\`)
@@ -385,8 +397,8 @@ describe('build-output-prerender', () => {
                 ▲ Next.js x.y.z (webpack)
                 - Experiments (use with caution):
                   ✓ cacheComponents (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
-                  ✓ clientParamParsing (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
-                  ✓ clientSegmentCache (enabled by \`__NEXT_EXPERIMENTAL_PPR\`)
+                  ✓ clientParamParsing (enabled by \`experimental.cacheComponents\`)
+                  ✓ clientSegmentCache (enabled by \`experimental.cacheComponents\`)
                   ✓ enablePrerenderSourceMaps (enabled by \`--debug-prerender\`)
                   ✓ ppr (enabled by \`__NEXT_EXPERIMENTAL_CACHE_COMPONENTS\`)
                   ⨯ prerenderEarlyExit (disabled by \`--debug-prerender\`)
