[Prefetch Inlining] Generate size-based hints on server

Part 1 of 2. This commit adds the server-side infrastructure for
size-based segment bundling but does not change any observable
behavior. The client-side changes that actually consume bundled
responses are in the next commit.

At build time, a measurement pass renders each segment's prefetch
response, measures its gzip size, and decides which segments should
be bundled together vs fetched separately. The decisions are
persisted to a manifest and embedded into the route tree prefetch
response so the client can act on them.

The decisions are computed once at build and remain fixed for the
lifetime of the deployment. They are not recomputed during
ISR/revalidation — if they could change, the client would need to
re-fetch the route tree after every revalidation, defeating the
purpose of caching it independently.

Refer to the next commit for a full description of the design and
motivation.

## Config

experimental.prefetchInlining accepts either a boolean or an object
with threshold overrides (maxSize, maxBundleSize). When true, the
default thresholds are used (2KB per-segment, 10KB total budget).
Eventually this will become the default; the flag exists only for
incremental rollout.

Author: acdlite

packages/next/src/build/index.ts

@@ -7,6 +7,7 @@ import type {
 import type { MiddlewareManifest } from './webpack/plugins/middleware-plugin'
 import type { ActionManifest } from './webpack/plugins/flight-client-entry-plugin'
 import type { CacheControl, Revalidate } from '../server/lib/cache-control'
+import type { PrefetchHints } from '../shared/lib/app-router-types'
 
 import '../lib/setup-exception-listeners'
 
@@ -61,6 +62,7 @@ import {
   IMAGES_MANIFEST,
   PAGES_MANIFEST,
   PHASE_PRODUCTION_BUILD,
+  PREFETCH_HINTS,
   PRERENDER_MANIFEST,
   REACT_LOADABLE_MANIFEST,
   ROUTES_MANIFEST,
@@ -2739,6 +2741,11 @@ export default async function build(
         preview: previewProps,
       }
 
+      // Accumulate per-route segment inlining decisions for
+      // prefetch-hints.json. First-writer-wins: if multiple param
+      // combinations exist for the same route pattern, use the first one.
+      const prefetchHints: Record<string, PrefetchHints> = {}
+
       const tbdPrerenderRoutes: string[] = []
 
       const { i18n } = config
@@ -3194,6 +3201,11 @@ export default async function build(
                 initialCacheControl: cacheControl,
               })
 
+              // Collect prefetch hints (first-writer-wins per page)
+              if (metadata.prefetchHints && !(page in prefetchHints)) {
+                prefetchHints[page] = metadata.prefetchHints
+              }
+
               if (cacheControl.revalidate !== 0) {
                 const normalizedRoute = normalizePagePath(route.pathname)
 
@@ -3369,6 +3381,11 @@ export default async function build(
                       builtSegmentDataRoute
                     )
                   }
+
+                  // Collect prefetch hints (first-writer-wins per page)
+                  if (metadata?.prefetchHints && !(page in prefetchHints)) {
+                    prefetchHints[page] = metadata.prefetchHints
+                  }
                 }
 
                 pageInfos.set(route.pathname, {
@@ -3958,6 +3975,12 @@ export default async function build(
           config.experimental.allowedRevalidateHeaderKeys
 
         await writePrerenderManifest(distDir, prerenderManifest)
+        if (Object.keys(prefetchHints).length > 0) {
+          await writeManifest(
+            path.join(distDir, SERVER_DIRECTORY, PREFETCH_HINTS),
+            prefetchHints
+          )
+        }
         await writeClientSsgManifest(prerenderManifest, {
           distDir,
           buildId,

packages/next/src/build/templates/app-page.ts

@@ -735,7 +735,8 @@ export async function handler(
               nextConfig.experimental.optimisticRouting
             ),
             inlineCss: Boolean(nextConfig.experimental.inlineCss),
-            prefetchInlining: Boolean(nextConfig.experimental.prefetchInlining),
+            prefetchInlining:
+              nextConfig.experimental.prefetchInlining ?? false,
             authInterrupts: Boolean(nextConfig.experimental.authInterrupts),
             clientTraceMetadata:
               nextConfig.experimental.clientTraceMetadata || ([] as any),

packages/next/src/build/templates/edge-ssr-app.ts

@@ -163,7 +163,7 @@ async function requestHandler(
         dynamicOnHover: Boolean(nextConfig.experimental.dynamicOnHover),
         optimisticRouting: Boolean(nextConfig.experimental.optimisticRouting),
         inlineCss: Boolean(nextConfig.experimental.inlineCss),
-        prefetchInlining: Boolean(nextConfig.experimental.prefetchInlining),
+        prefetchInlining: nextConfig.experimental.prefetchInlining ?? false,
         authInterrupts: Boolean(nextConfig.experimental.authInterrupts),
         clientTraceMetadata:
           nextConfig.experimental.clientTraceMetadata || ([] as any),

packages/next/src/client/components/router-reducer/create-initial-router-state.ts

@@ -65,6 +65,13 @@ export function createInitialRouterState({
   // NOTE: The metadataVaryPath isn't used for anything currently because the
   // head is embedded into the CacheNode tree, but eventually we'll lift it out
   // and store it on the top-level state object.
+  //
+  // TODO: For statically-generated-at-build-time HTML pages, the
+  // FlightRouterState baked into the initial RSC payload won't have the
+  // correct segment inlining hints (ParentInlinedIntoSelf, InlinedIntoChild)
+  // because those are computed after the pre-render. The client will need to
+  // fetch the correct hints from the route tree prefetch (/_tree) response
+  // before acting on inlining decisions.
   const acc = { metadataVaryPath: null }
   const initialRouteTree = convertRootFlightRouterStateToRouteTree(
     initialTree,

packages/next/src/export/routes/app-page.ts

@@ -100,6 +100,7 @@ export async function exportAppPage(
       fetchTags,
       fetchMetrics,
       segmentData,
+      prefetchHints,
       renderResumeDataCache,
     } = metadata
 
@@ -218,6 +219,7 @@ export async function exportAppPage(
       headers,
       postponed,
       segmentPaths,
+      prefetchHints,
     }
 
     fileWriter.append(
@@ -231,6 +233,7 @@ export async function exportAppPage(
         ? meta
         : {
             segmentPaths: meta.segmentPaths,
+            prefetchHints: meta.prefetchHints,
           },
       hasEmptyStaticShell: Boolean(postponed) && html === '',
       hasPostponed: Boolean(postponed),

packages/next/src/export/routes/types.ts

@@ -1,8 +1,10 @@
 import type { OutgoingHttpHeaders } from 'node:http'
+import type { PrefetchHints } from '../../shared/lib/app-router-types'
 
 export type RouteMetadata = {
   status: number | undefined
   headers: OutgoingHttpHeaders | undefined
   postponed: string | undefined
   segmentPaths: Array<string> | undefined
+  prefetchHints: PrefetchHints | undefined
 }

packages/next/src/server/app-render/app-render.tsx

@@ -11,6 +11,7 @@ import type {
   FlightData,
   InitialRSCPayload,
   FlightDataPath,
+  PrefetchHints,
 } from '../../shared/lib/app-router-types'
 import type { Readable } from 'node:stream'
 import {
@@ -605,6 +606,7 @@ async function generateDynamicRSCPayload(
             rootLayoutIncluded: false,
             preloadCallbacks,
             MetadataOutlet,
+            hintTree: ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null,
           })
     ).map((path) => path.slice(1)) // remove the '' (root) segment
   }
@@ -1635,8 +1637,10 @@ async function getRSCPayload(
     workStore,
   } = ctx
 
+  const hints = ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null
   const initialTree = await createFlightRouterStateFromLoaderTree(
     tree,
+    hints,
     getDynamicParamFromSegment,
     query
   )
@@ -1815,8 +1819,10 @@ async function getErrorRSCPayload(
     createElement(Metadata, null)
   )
 
+  const errorHints = ctx.renderOpts.prefetchHints?.[ctx.pagePath] ?? null
   const initialTree = await createFlightRouterStateFromLoaderTree(
     tree,
+    errorHints,
     getDynamicParamFromSegment,
     query
   )
@@ -5534,11 +5540,13 @@ async function prerenderToStream(
 
       // collectSegmentData needs the raw flight data without the marker byte.
       const flightData = metadata.flightData.subarray(1)
-      metadata.segmentData = await collectSegmentData(
+      await collectSegmentData(
         flightData,
         finalServerPrerenderStore,
         ComponentMod,
-        renderOpts
+        renderOpts,
+        ctx.pagePath,
+        metadata
       )
 
       if (serverIsDynamic) {
@@ -5788,11 +5796,13 @@ async function prerenderToStream(
 
       if (shouldGenerateStaticFlightData(workStore)) {
         metadata.flightData = flightData
-        metadata.segmentData = await collectSegmentData(
+        await collectSegmentData(
           flightData,
           ssrPrerenderStore,
           ComponentMod,
-          renderOpts
+          renderOpts,
+          ctx.pagePath,
+          metadata
         )
       }
 
@@ -5997,11 +6007,13 @@ async function prerenderToStream(
       if (shouldGenerateStaticFlightData(workStore)) {
         const flightData = await streamToBuffer(reactServerResult.asStream())
         metadata.flightData = flightData
-        metadata.segmentData = await collectSegmentData(
+        await collectSegmentData(
           flightData,
           prerenderLegacyStore,
           ComponentMod,
-          renderOpts
+          renderOpts,
+          ctx.pagePath,
+          metadata
         )
       }
 
@@ -6165,11 +6177,13 @@ async function prerenderToStream(
           reactServerPrerenderResult.asStream()
         )
         metadata.flightData = flightData
-        metadata.segmentData = await collectSegmentData(
+        await collectSegmentData(
           flightData,
           prerenderLegacyStore,
           ComponentMod,
-          renderOpts
+          renderOpts,
+          ctx.pagePath,
+          metadata
         )
       }
 
@@ -6289,8 +6303,10 @@ async function collectSegmentData(
   fullPageDataBuffer: Buffer,
   prerenderStore: PrerenderStore,
   ComponentMod: AppPageModule,
-  renderOpts: RenderOpts
-): Promise<Map<string, Buffer> | undefined> {
+  renderOpts: RenderOpts,
+  pagePath: string,
+  metadata: AppPageRenderResultMetadata
+): Promise<void> {
   // Per-segment prefetch data
   //
   // All of the segments for a page are generated simultaneously, including
@@ -6321,13 +6337,51 @@ async function collectSegmentData(
 
   const selectStaleTime = createSelectStaleTime(renderOpts.experimental)
   const staleTime = selectStaleTime(prerenderStore.stale)
-  return await ComponentMod.collectSegmentData(
+
+  // Resolve prefetch hints. At runtime (next start / ISR), the precomputed
+  // hints are already loaded from the prefetch-hints.json manifest. During
+  // build, compute them by measuring segment gzip sizes and write them to
+  // metadata so the build pipeline can persist them to the manifest.
+  let hints: PrefetchHints | null
+  if (renderOpts.isBuildTimePrerendering) {
+    // Build time: compute fresh hints and store in metadata for the manifest.
+    const prefetchInlining = renderOpts.experimental.prefetchInlining
+    const maxSize =
+      typeof prefetchInlining === 'object'
+        ? (prefetchInlining.maxSize ?? 2_048)
+        : 2_048
+    const maxBundleSize =
+      typeof prefetchInlining === 'object'
+        ? (prefetchInlining.maxBundleSize ?? 10_240)
+        : 10_240
+    hints = await ComponentMod.collectPrefetchHints(
+      fullPageDataBuffer,
+      staleTime,
+      clientModules,
+      serverConsumerManifest,
+      maxSize,
+      maxBundleSize
+    )
+    metadata.prefetchHints = hints
+  } else {
+    // Runtime: use hints from the manifest. Never compute fresh hints
+    // during ISR/revalidation.
+    hints = renderOpts.prefetchHints?.[pagePath] ?? null
+  }
+
+  // Pass the resolved hints so collectSegmentData can union them into
+  // the TreePrefetch. During the initial build the FlightRouterState in
+  // the buffer doesn't have inlining hints yet (they were just computed
+  // above), so we need to merge them in here. At runtime/ISR the hints
+  // are already embedded in the FlightRouterState, so this is null.
+  metadata.segmentData = await ComponentMod.collectSegmentData(
     renderOpts.cacheComponents,
     fullPageDataBuffer,
     staleTime,
     clientModules,
     serverConsumerManifest,
-    renderOpts.experimental.prefetchInlining
+    Boolean(renderOpts.experimental.prefetchInlining),
+    hints
   )
 }