feat(app-router): add comprehensive fallback parameter collection and validation system

Introduces new fallback parameter collection mechanism spanning build-time static path
generation, runtime parameter resolution, and client-side parsing. Adds FallbackRouteParam
types, collectFallbackRouteParams functionality, enhanced parameter validation in app
segments, and improved error handling for dynamic route parameters across the entire
App Router pipeline.

Author: wyattjoh

packages/next/errors.json

@@ -779,5 +779,6 @@
   "778": "`prerenderAndAbortInSequentialTasksWithStages` should not be called in edge runtime.",
   "779": "Route %s used \"searchParams\" inside \"use cache\". Accessing dynamic request data inside a cache scope is not supported. If you need some search params inside a cached function await \"searchParams\" outside of the cached function and pass only the required search params as arguments to the cached function. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache",
   "780": "Invariant: failed to find parent dynamic route for notFound route %s",
-  "781": "\\`experimental.clientParamParsing\\` can not be \\`true\\` when \\`experimental.clientSegmentCache\\` is \\`false\\`. Client param parsing is only relevant when client segment cache is enabled."
+  "781": "\\`experimental.clientParamParsing\\` can not be \\`true\\` when \\`experimental.clientSegmentCache\\` is \\`false\\`. Client param parsing is only relevant when client segment cache is enabled.",
+  "782": "Unexpected dynamic param type: %s"
 }

packages/next/src/build/index.ts

@@ -140,7 +140,7 @@ import {
   collectMeta,
 } from './utils'
 import type { PageInfo, PageInfos } from './utils'
-import type { PrerenderedRoute } from './static-paths/types'
+import type { FallbackRouteParam, PrerenderedRoute } from './static-paths/types'
 import type { AppSegmentConfig } from './segment-config/app/app-segment-config'
 import { writeBuildId } from './write-build-id'
 import { normalizeLocalePath } from '../shared/lib/i18n/normalize-locale-path'
@@ -320,6 +320,12 @@ export interface DynamicPrerenderManifestRoute {
    */
   fallbackRootParams: readonly string[] | undefined
 
+  /**
+   * The fallback route params for this route that were parsed from the loader
+   * tree.
+   */
+  fallbackRouteParams: readonly FallbackRouteParam[] | undefined
+
   /**
    * The source route that this fallback route is based on. This is a reference
    * so that we can associate this dynamic route with the correct source.
@@ -3100,7 +3106,12 @@ export default async function build(
             for (const prerenderedRoute of prerenderedRoutes) {
               if (
                 prerenderedRoute.fallbackRouteParams &&
-                prerenderedRoute.fallbackRouteParams.length > 0
+                prerenderedRoute.fallbackRouteParams.length > 0 &&
+                // If all the fallback route params are parallel route params,
+                // then we still consider it a known route.
+                !prerenderedRoute.fallbackRouteParams.every(
+                  (param) => param.isParallelRouteParam
+                )
               ) {
                 unsortedUnknownPrerenderRoutes.push(prerenderedRoute)
               } else {
@@ -3126,7 +3137,12 @@ export default async function build(
               if (
                 isRoutePPREnabled &&
                 prerenderedRoute.fallbackRouteParams &&
-                prerenderedRoute.fallbackRouteParams.length > 0
+                prerenderedRoute.fallbackRouteParams.length > 0 &&
+                // If all the fallback route params are parallel route params,
+                // then we still consider it a static route.
+                !prerenderedRoute.fallbackRouteParams.every(
+                  (param) => param.isParallelRouteParam
+                )
               ) {
                 // If the route has unknown params, then we need to add it to
                 // the list of dynamic routes.
@@ -3432,9 +3448,17 @@ export default async function build(
                   fallbackRootParams: fallback
                     ? route.fallbackRootParams
                     : undefined,
-                  fallbackSourceRoute: route.fallbackRouteParams?.length
-                    ? page
-                    : undefined,
+                  fallbackSourceRoute:
+                    route.fallbackRouteParams &&
+                    route.fallbackRouteParams.length > 0 &&
+                    // If all the fallback route params are parallel route
+                    // params, then we still consider it a static route.
+                    !route.fallbackRouteParams.every(
+                      (param) => param.isParallelRouteParam
+                    )
+                      ? page
+                      : undefined,
+                  fallbackRouteParams: route.fallbackRouteParams,
                   dataRouteRegex: !dataRoute
                     ? null
                     : normalizeRouteRegex(
@@ -3901,6 +3925,7 @@ export default async function build(
             fallbackExpire: undefined,
             fallbackSourceRoute: undefined,
             fallbackRootParams: undefined,
+            fallbackRouteParams: undefined,
             dataRouteRegex: normalizeRouteRegex(
               getNamedRouteRegex(dataRoute, {
                 prefixRouteKeys: true,

packages/next/src/build/segment-config/app/app-segments.ts

@@ -1,13 +1,6 @@
-import type { LoadComponentsReturnType } from '../../../server/load-components'
 import type { Params } from '../../../server/request/params'
-import type {
-  AppPageRouteModule,
-  AppPageModule,
-} from '../../../server/route-modules/app-page/module.compiled'
-import type {
-  AppRouteRouteModule,
-  AppRouteModule,
-} from '../../../server/route-modules/app-route/module.compiled'
+import type { AppPageRouteModule } from '../../../server/route-modules/app-page/module.compiled'
+import type { AppRouteRouteModule } from '../../../server/route-modules/app-route/module.compiled'
 import {
   type AppSegmentConfig,
   parseAppSegmentConfig,
@@ -25,6 +18,8 @@ import {
   type LoaderTree,
 } from '../../../server/lib/app-dir-module'
 import { PAGE_SEGMENT_KEY } from '../../../shared/lib/segment'
+import type { FallbackRouteParam } from '../../static-paths/types'
+import { createFallbackRouteParam } from '../../static-paths/utils'
 
 type GenerateStaticParams = (options: { params?: Params }) => Promise<Params[]>
 
@@ -63,11 +58,17 @@ function attach(segment: AppSegment, userland: unknown, route: string) {
 
 export type AppSegment = {
   name: string
-  param: string | undefined
+  paramName: string | undefined
   filePath: string | undefined
   config: AppSegmentConfig | undefined
   isDynamicSegment: boolean
   generateStaticParams: GenerateStaticParams | undefined
+
+  /**
+   * Whether this segment is a parallel route segment or descends from a
+   * parallel route segment.
+   */
+  isParallelRouteSegment: boolean | undefined
 }
 
 /**
@@ -81,27 +82,32 @@ async function collectAppPageSegments(routeModule: AppPageRouteModule) {
   // to see the same segment multiple times.
   const uniqueSegments = new Map<string, AppSegment>()
 
-  // Queue will store tuples of [loaderTree, currentSegments]
-  type QueueItem = [LoaderTree, AppSegment[]]
-  const queue: QueueItem[] = [[routeModule.userland.loaderTree, []]]
+  // Queue will store tuples of [loaderTree, currentSegments, isParallelRouteSegment]
+  type QueueItem = [
+    loaderTree: LoaderTree,
+    currentSegments: AppSegment[],
+    isParallelRouteSegment: boolean,
+  ]
+  const queue: QueueItem[] = [[routeModule.userland.loaderTree, [], false]]
 
   while (queue.length > 0) {
-    const [loaderTree, currentSegments] = queue.shift()!
+    const [loaderTree, currentSegments, isParallelRouteSegment] = queue.shift()!
     const [name, parallelRoutes] = loaderTree
 
     // Process current node
     const { mod: userland, filePath } = await getLayoutOrPageModule(loaderTree)
     const isClientComponent = userland && isClientReference(userland)
 
-    const param = getSegmentParam(name)?.param
+    const paramName = getSegmentParam(name)?.param
 
     const segment: AppSegment = {
       name,
-      param,
+      paramName,
       filePath,
       config: undefined,
-      isDynamicSegment: !!param,
+      isDynamicSegment: !!paramName,
       generateStaticParams: undefined,
+      isParallelRouteSegment,
     }
 
     // Only server components can have app segment configurations
@@ -129,15 +135,21 @@ async function collectAppPageSegments(routeModule: AppPageRouteModule) {
     // Add all parallel routes to the queue
     for (const parallelRouteKey in parallelRoutes) {
       const parallelRoute = parallelRoutes[parallelRouteKey]
-      queue.push([parallelRoute, updatedSegments])
+      queue.push([
+        parallelRoute,
+        updatedSegments,
+        // A parallel route segment is one that descends from a segment that is
+        // not children or descends from a parallel route segment.
+        isParallelRouteSegment || parallelRouteKey !== 'children',
+      ])
     }
   }
 
   return Array.from(uniqueSegments.values())
 }
 
 function getSegmentKey(segment: AppSegment) {
-  return `${segment.name}-${segment.filePath ?? ''}-${segment.param ?? ''}`
+  return `${segment.name}-${segment.filePath ?? ''}-${segment.paramName ?? ''}`
 }
 
 /**
@@ -157,16 +169,17 @@ function collectAppRouteSegments(
 
   // Generate all the segments.
   const segments: AppSegment[] = parts.map((name) => {
-    const param = getSegmentParam(name)?.param
+    const paramName = getSegmentParam(name)?.param
 
     return {
       name,
-      param,
+      paramName,
       filePath: undefined,
-      isDynamicSegment: !!param,
+      isDynamicSegment: !!paramName,
       config: undefined,
       generateStaticParams: undefined,
-    }
+      isParallelRouteSegment: undefined,
+    } satisfies AppSegment
   })
 
   // We know we have at least one, we verified this above. We should get the
@@ -187,11 +200,9 @@ function collectAppRouteSegments(
  * @param components the loaded components
  * @returns the segments for the route module
  */
-export function collectSegments({
-  routeModule,
-}: LoadComponentsReturnType<AppPageModule | AppRouteModule>):
-  | Promise<AppSegment[]>
-  | AppSegment[] {
+export function collectSegments(
+  routeModule: AppRouteRouteModule | AppPageRouteModule
+): Promise<AppSegment[]> | AppSegment[] {
   if (isAppRouteRouteModule(routeModule)) {
     return collectAppRouteSegments(routeModule)
   }
@@ -204,3 +215,51 @@ export function collectSegments({
     'Expected a route module to be one of app route or page'
   )
 }
+
+/**
+ * Collects the fallback route params for a given app page route module. This is
+ * a variant of the `collectSegments` function that only collects the fallback
+ * route params without importing anything.
+ *
+ * @param routeModule the app page route module
+ * @returns the fallback route params for the app page route module
+ */
+export function collectFallbackRouteParams(
+  routeModule: AppPageRouteModule
+): readonly FallbackRouteParam[] {
+  const uniqueSegments = new Map<string, FallbackRouteParam>()
+
+  // Queue will store tuples of [loaderTree, isParallelRouteSegment]
+  type QueueItem = [loaderTree: LoaderTree, isParallelRouteSegment: boolean]
+  const queue: QueueItem[] = [[routeModule.userland.loaderTree, false]]
+
+  while (queue.length > 0) {
+    const [loaderTree, isParallelRouteSegment] = queue.shift()!
+    const [name, parallelRoutes] = loaderTree
+
+    // Handle this segment (if it's a dynamic segment param).
+    const segmentParam = getSegmentParam(name)
+    if (segmentParam) {
+      const key = `${name}-${segmentParam.param}`
+      if (!uniqueSegments.has(key)) {
+        uniqueSegments.set(
+          key,
+          createFallbackRouteParam(segmentParam.param, isParallelRouteSegment)
+        )
+      }
+    }
+
+    // Add all of this segment's parallel routes to the queue.
+    for (const parallelRouteKey in parallelRoutes) {
+      const parallelRoute = parallelRoutes[parallelRouteKey]
+      queue.push([
+        parallelRoute,
+        // A parallel route segment is one that descends from a segment that is
+        // not children or descends from a parallel route segment.
+        isParallelRouteSegment || parallelRouteKey !== 'children',
+      ])
+    }
+  }
+
+  return Array.from(uniqueSegments.values())
+}