Unverified Commit 5b998d69 authored by Wyatt Johnson's avatar Wyatt Johnson Committed by GitHub

fix: revert client segment route changes for sub shell generation (#81740)

### What?

Implements a new sortable routes system that distinguishes between
source pages and rendered pages for sub-shell generation.

### Why?

The existing route sorting logic in Next.js doesn't account for the
distinction between the original page definition (`sourcePage`) and the
final rendered route (`page`). This is critical for sub-shell
generation, given this example:

| Page | Source Page |
|--------|--------|
| `/en/[teamSlug]/[projectSlug]/monitoring` |
`/[lang]/[teamSlug]/[projectSlug]/monitoring` |
| `/fr/[teamSlug]/[projectSlug]/monitoring` |
`/[lang]/[teamSlug]/[projectSlug]/monitoring` |
| `/[lang]/[teamSlug]/~/monitoring` | `/[lang]/[teamSlug]/~/monitoring`
|

And a request to `/en/vercel/~/monitoring` that it will hit the
`/[lang]/[teamSlug]/~/monitoring` page instead of the
`/en/[teamSlug]/[projectSlug]/monitoring`. This is because we first need
to sort by the Source Page and then the Page to ensure that the correct
route ordering is respected.

### How?

- Adds new `SortableRoute` type that tracks both `sourcePage` and `page`
- Implements depth-first route comparison algorithm that properly
handles segment specificity
- Refactors build process to use the new sorting functions instead of
legacy `getSortedRoutes`
- Adds source page tracking for PPR-enabled routes with
`clientSegmentEnabled`
- Includes comprehensive test coverage for all route sorting scenarios

The new sorting algorithm ensures consistent route ordering across
builds and proper sub-shell generation behavior.
parent cff812b4
...@@ -81,11 +81,7 @@ import { ...@@ -81,11 +81,7 @@ import {
DYNAMIC_CSS_MANIFEST, DYNAMIC_CSS_MANIFEST,
TURBOPACK_CLIENT_MIDDLEWARE_MANIFEST, TURBOPACK_CLIENT_MIDDLEWARE_MANIFEST,
} from '../shared/lib/constants' } from '../shared/lib/constants'
import { import { isDynamicRoute } from '../shared/lib/router/utils'
getSortedRoutes,
isDynamicRoute,
getSortedRouteObjects,
} from '../shared/lib/router/utils'
import type { __ApiPreviewProps } from '../server/api-utils' import type { __ApiPreviewProps } from '../server/api-utils'
import loadConfig from '../server/config' import loadConfig from '../server/config'
import type { BuildManifest } from '../server/get-page-files' import type { BuildManifest } from '../server/get-page-files'
...@@ -210,6 +206,11 @@ import { extractNextErrorCode } from '../lib/error-telemetry-utils' ...@@ -210,6 +206,11 @@ import { extractNextErrorCode } from '../lib/error-telemetry-utils'
import { runAfterProductionCompile } from './after-production-compile' import { runAfterProductionCompile } from './after-production-compile'
import { generatePreviewKeys } from './preview-key-utils' import { generatePreviewKeys } from './preview-key-utils'
import { handleBuildComplete } from './adapter/build-complete' import { handleBuildComplete } from './adapter/build-complete'
import {
sortPageObjects,
sortPages,
sortSortableRouteObjects,
} from '../shared/lib/router/utils/sortable-routes'
type Fallback = null | boolean | string type Fallback = null | boolean | string
...@@ -430,7 +431,7 @@ export type RoutesManifest = { ...@@ -430,7 +431,7 @@ export type RoutesManifest = {
} }
headers: Array<ManifestHeaderRoute> headers: Array<ManifestHeaderRoute>
staticRoutes: Array<ManifestRoute> staticRoutes: Array<ManifestRoute>
dynamicRoutes: Array<ManifestRoute> dynamicRoutes: ReadonlyArray<ManifestRoute>
dataRoutes: Array<ManifestDataRoute> dataRoutes: Array<ManifestDataRoute>
i18n?: { i18n?: {
domains?: ReadonlyArray<{ domains?: ReadonlyArray<{
...@@ -1328,14 +1329,20 @@ export default async function build( ...@@ -1328,14 +1329,20 @@ export default async function build(
const isAppPPREnabled = checkIsAppPPREnabled(config.experimental.ppr) const isAppPPREnabled = checkIsAppPPREnabled(config.experimental.ppr)
const routesManifestPath = path.join(distDir, ROUTES_MANIFEST) const routesManifestPath = path.join(distDir, ROUTES_MANIFEST)
const dynamicRoutes: Array<ManifestRoute> = []
/**
* A map of all the pages to their sourcePage value. This is only used for
* routes that have PPR enabled and clientSegmentEnabled is true.
*/
const sourcePages = new Map<string, string>()
const routesManifest: RoutesManifest = nextBuildSpan const routesManifest: RoutesManifest = nextBuildSpan
.traceChild('generate-routes-manifest') .traceChild('generate-routes-manifest')
.traceFn(() => { .traceFn(() => {
const sortedRoutes = getSortedRoutes([ const sortedRoutes = sortPages([
...pageKeys.pages, ...pageKeys.pages,
...(pageKeys.app ?? []), ...(pageKeys.app ?? []),
]) ])
const dynamicRoutes: Array<ManifestRoute> = []
const staticRoutes: Array<ManifestRoute> = [] const staticRoutes: Array<ManifestRoute> = []
for (const route of sortedRoutes) { for (const route of sortedRoutes) {
...@@ -2466,7 +2473,7 @@ export default async function build( ...@@ -2466,7 +2473,7 @@ export default async function build(
if (serverPropsPages.size > 0 || ssgPages.size > 0) { if (serverPropsPages.size > 0 || ssgPages.size > 0) {
// We update the routes manifest after the build with the // We update the routes manifest after the build with the
// data routes since we can't determine these until after build // data routes since we can't determine these until after build
routesManifest.dataRoutes = getSortedRoutes([ routesManifest.dataRoutes = sortPages([
...serverPropsPages, ...serverPropsPages,
...ssgPages, ...ssgPages,
]).map((page) => { ]).map((page) => {
...@@ -2930,39 +2937,39 @@ export default async function build( ...@@ -2930,39 +2937,39 @@ export default async function build(
// route), any routes that were generated with unknown route params // route), any routes that were generated with unknown route params
// should be collected and included in the dynamic routes part // should be collected and included in the dynamic routes part
// of the manifest instead. // of the manifest instead.
const routes: PrerenderedRoute[] = [] const staticPrerenderedRoutes: PrerenderedRoute[] = []
const dynamicRoutes: PrerenderedRoute[] = [] const dynamicPrerenderedRoutes: PrerenderedRoute[] = []
// Sort the outputted routes to ensure consistent output. Any route // Sort the outputted routes to ensure consistent output. Any route
// though that has unknown route params will be pulled and sorted // though that has unknown route params will be pulled and sorted
// independently. This is because the routes with unknown route // independently. This is because the routes with unknown route
// params will contain the dynamic path parameters, some of which // params will contain the dynamic path parameters, some of which
// may conflict with the actual prerendered routes. // may conflict with the actual prerendered routes.
let unknownPrerenderRoutes: PrerenderedRoute[] = [] const unsortedUnknownPrerenderRoutes: PrerenderedRoute[] = []
let knownPrerenderRoutes: PrerenderedRoute[] = [] const unsortedKnownPrerenderRoutes: PrerenderedRoute[] = []
for (const prerenderedRoute of prerenderedRoutes) { for (const prerenderedRoute of prerenderedRoutes) {
if ( if (
prerenderedRoute.fallbackRouteParams && prerenderedRoute.fallbackRouteParams &&
prerenderedRoute.fallbackRouteParams.length > 0 prerenderedRoute.fallbackRouteParams.length > 0
) { ) {
unknownPrerenderRoutes.push(prerenderedRoute) unsortedUnknownPrerenderRoutes.push(prerenderedRoute)
} else { } else {
knownPrerenderRoutes.push(prerenderedRoute) unsortedKnownPrerenderRoutes.push(prerenderedRoute)
} }
} }
unknownPrerenderRoutes = getSortedRouteObjects( const sortedUnknownPrerenderRoutes = sortPageObjects(
unknownPrerenderRoutes, unsortedUnknownPrerenderRoutes,
(prerenderedRoute) => prerenderedRoute.pathname (prerenderedRoute) => prerenderedRoute.pathname
) )
knownPrerenderRoutes = getSortedRouteObjects( const sortedKnownPrerenderRoutes = sortPageObjects(
knownPrerenderRoutes, unsortedKnownPrerenderRoutes,
(prerenderedRoute) => prerenderedRoute.pathname (prerenderedRoute) => prerenderedRoute.pathname
) )
prerenderedRoutes = [ prerenderedRoutes = [
...knownPrerenderRoutes, ...sortedKnownPrerenderRoutes,
...unknownPrerenderRoutes, ...sortedUnknownPrerenderRoutes,
] ]
for (const prerenderedRoute of prerenderedRoutes) { for (const prerenderedRoute of prerenderedRoutes) {
...@@ -2979,16 +2986,16 @@ export default async function build( ...@@ -2979,16 +2986,16 @@ export default async function build(
) { ) {
// If the route has unknown params, then we need to add it to // If the route has unknown params, then we need to add it to
// the list of dynamic routes. // the list of dynamic routes.
dynamicRoutes.push(prerenderedRoute) dynamicPrerenderedRoutes.push(prerenderedRoute)
} else { } else {
// If the route doesn't have unknown params, then we need to // If the route doesn't have unknown params, then we need to
// add it to the list of routes. // add it to the list of static routes.
routes.push(prerenderedRoute) staticPrerenderedRoutes.push(prerenderedRoute)
} }
} }
// Handle all the static routes. // Handle all the static routes.
for (const route of routes) { for (const route of staticPrerenderedRoutes) {
if (isDynamicRoute(page) && route.pathname === page) continue if (isDynamicRoute(page) && route.pathname === page) continue
if (route.pathname === UNDERSCORE_NOT_FOUND_ROUTE) continue if (route.pathname === UNDERSCORE_NOT_FOUND_ROUTE) continue
...@@ -3075,7 +3082,7 @@ export default async function build( ...@@ -3075,7 +3082,7 @@ export default async function build(
// they are enabled, then it'll already be included in the // they are enabled, then it'll already be included in the
// prerendered routes. // prerendered routes.
if (!isRoutePPREnabled) { if (!isRoutePPREnabled) {
dynamicRoutes.push({ dynamicPrerenderedRoutes.push({
params: {}, params: {},
pathname: page, pathname: page,
encodedPathname: page, encodedPathname: page,
...@@ -3088,7 +3095,7 @@ export default async function build( ...@@ -3088,7 +3095,7 @@ export default async function build(
}) })
} }
for (const route of dynamicRoutes) { for (const route of dynamicPrerenderedRoutes) {
const normalizedRoute = normalizePagePath(route.pathname) const normalizedRoute = normalizePagePath(route.pathname)
const metadata = exportResult.byPath.get( const metadata = exportResult.byPath.get(
...@@ -3103,18 +3110,43 @@ export default async function build( ...@@ -3103,18 +3110,43 @@ export default async function build(
} }
let prefetchDataRoute: string | undefined let prefetchDataRoute: string | undefined
let dynamicRoute = routesManifest.dynamicRoutes.find(
(r) => r.page === route.pathname
)
if (!isAppRouteHandler && isAppPPREnabled) { if (!isAppRouteHandler && isAppPPREnabled) {
prefetchDataRoute = path.posix.join( prefetchDataRoute = path.posix.join(
`${normalizedRoute}${RSC_PREFETCH_SUFFIX}` `${normalizedRoute}${RSC_PREFETCH_SUFFIX}`
) )
// If the dynamic route wasn't found, then we need to create
// it. This ensures that for each fallback shell there's an
// entry in the app routes manifest which enables routing for
// this fallback shell.
if (!dynamicRoute) {
dynamicRoute = pageToRoute(route.pathname)
sourcePages.set(route.pathname, page)
// This route is not for the internal router, but instead
// for external routers.
dynamicRoute.skipInternalRouting = true
// Push this to the end of the array. The dynamic routes are
// sorted by page later.
dynamicRoutes.push(dynamicRoute)
}
} }
if (!isAppRouteHandler && metadata?.segmentPaths) { if (!isAppRouteHandler && metadata?.segmentPaths) {
const dynamicRoute = routesManifest.dynamicRoutes.find( // If PPR isn't enabled, then we might not find the dynamic
(r) => r.page === page // route by pathname. If that's the case, we need to find the
) // route by page.
if (!dynamicRoute) { if (!dynamicRoute) {
throw new InvariantError('Dynamic route not found') dynamicRoute = dynamicRoutes.find((r) => r.page === page)
// If it can't be found by page, we must throw an error.
if (!dynamicRoute) {
throw new InvariantError('Dynamic route not found')
}
} }
dynamicRoute.prefetchSegmentDataRoutes ??= [] dynamicRoute.prefetchSegmentDataRoutes ??= []
...@@ -3573,11 +3605,16 @@ export default async function build( ...@@ -3573,11 +3605,16 @@ export default async function build(
} }
}) })
// As we may have modified the routesManifest.dynamicRoutes, we need to // As we may have modified the dynamicRoutes, we need to sort the
// sort the dynamic routes by page. // dynamic routes by page.
routesManifest.dynamicRoutes = getSortedRouteObjects( routesManifest.dynamicRoutes = sortSortableRouteObjects(
routesManifest.dynamicRoutes, dynamicRoutes,
(route) => route.page (route) => ({
// If the route is PPR enabled, and has an associated source page,
// use it. Otherwise fallback to the page which should be the same.
sourcePage: sourcePages.get(route.page) ?? route.page,
page: route.page,
})
) )
// Now write the routes manifest out. // Now write the routes manifest out.
......
...@@ -18,6 +18,7 @@ import type { ...@@ -18,6 +18,7 @@ import type {
ManifestHeaderRoute, ManifestHeaderRoute,
ManifestRedirectRoute, ManifestRedirectRoute,
RouteType, RouteType,
ManifestRoute,
} from '../build' } from '../build'
import { isStableBuild } from '../shared/lib/canary-only' import { isStableBuild } from '../shared/lib/canary-only'
...@@ -63,7 +64,7 @@ export interface NextAdapter { ...@@ -63,7 +64,7 @@ export interface NextAdapter {
afterFiles: Array<ManifestRewriteRoute> afterFiles: Array<ManifestRewriteRoute>
fallback: Array<ManifestRewriteRoute> fallback: Array<ManifestRewriteRoute>
} }
dynamicRoutes: Array<{}> dynamicRoutes: ReadonlyArray<ManifestRoute>
} }
outputs: AdapterOutputs outputs: AdapterOutputs
}) => Promise<void> | void }) => Promise<void> | void
......
/**
* A route that can be sorted by specificity.
*/
export type SortableRoute = {
/**
* The source page of the route. This represents the original page that's on
* disk. For example, the `app/[lang]/[...rest]/page.tsx` would have a source
* page of '/[lang]/[...rest]'.
*/
readonly sourcePage: string
/**
* The page of the route. This represents the final rendered route. For
* example, the `app/[lang]/[...rest]/page.tsx` that was rendered with a lang
* value of `en` would have a page of '/en/[...rest]'.
*/
readonly page: string
}
/**
* Determines the specificity of a route segment for sorting purposes.
*
* In Next.js routing, more specific routes should match before less specific ones.
* This function returns a numeric value where lower numbers indicate higher specificity.
*
* Specificity order (most to least specific):
* 1. Static segments (e.g., "about", "api") - return 0
* 2. Dynamic segments (e.g., "[id]", "[slug]") - return 1
* 3. Catch-all segments (e.g., "[...slug]") - return 2
* 4. Optional catch-all segments (e.g., "[[...slug]]") - return 3
*
* @param segment - A single path segment (e.g., "api", "[id]", "[...slug]")
* @returns A numeric specificity value (0-3, where 0 is most specific)
*/
export function getSegmentSpecificity(segment: string): number {
// Static segments are most specific - they match exactly one path
if (!segment.includes('[')) {
return 0
}
// Optional catch-all [[...param]] is least specific - matches zero or more segments
if (segment.startsWith('[[...') && segment.endsWith(']]')) {
return 3
}
// Catch-all [...param] is less specific - matches one or more segments
if (segment.startsWith('[...') && segment.endsWith(']')) {
return 2
}
// Regular dynamic [param] is more specific than catch-all - matches exactly one segment
if (segment.startsWith('[') && segment.endsWith(']')) {
return 1
}
// Default to static (fallback case)
return 0
}
/**
* Compares two route paths using a depth-first traversal approach.
*
* This function implements a deterministic comparison that sorts routes by specificity:
* 1. More specific routes come first (fewer dynamic segments)
* 2. Shorter routes are more specific than longer ones
* 3. Routes with same specificity are sorted lexicographically
*
* The comparison is done segment by segment, left to right, similar to how
* you would traverse a route tree in depth-first order.
*
* @param pathA - First route path to compare (e.g., "/api/users/[id]")
* @param pathB - Second route path to compare (e.g., "/api/[...slug]")
* @returns Negative if pathA is more specific, positive if pathB is more specific, 0 if equal
*/
export function compareRouteSegments(pathA: string, pathB: string): number {
// Split paths into segments, removing empty strings from leading/trailing slashes
const segmentsA = pathA.split('/').filter(Boolean)
const segmentsB = pathB.split('/').filter(Boolean)
// Compare segment by segment up to the length of the longer path
const maxLength = Math.max(segmentsA.length, segmentsB.length)
for (let i = 0; i < maxLength; i++) {
const segA = segmentsA[i] || ''
const segB = segmentsB[i] || ''
// Handle length differences: shorter routes are MORE specific
// Example: "/api" is more specific than "/api/users"
if (!segA && segB) return -1 // pathA is shorter, so more specific
if (segA && !segB) return 1 // pathB is shorter, so more specific
if (!segA && !segB) return 0 // Both paths ended, they're equal
// Compare segment specificity using our specificity scoring
const specificityA = getSegmentSpecificity(segA)
const specificityB = getSegmentSpecificity(segB)
// Lower specificity number = more specific route
// Example: "api" (0) vs "[slug]" (1) - "api" wins
if (specificityA !== specificityB) {
return specificityA - specificityB
}
// If segments have same specificity, compare lexicographically for determinism
// Example: "[id]" vs "[slug]" - "[id]" comes first alphabetically
if (segA !== segB) {
return segA.localeCompare(segB)
}
// Segments are identical, continue to next segment
}
// All segments compared equally
return 0
}
/**
* Compares two complete routes for sorting purposes.
*
* Routes are compared with a two-tier priority system:
* 1. Primary: Compare by source path specificity
* 2. Secondary: If sources are equal, compare by page path specificity
*
* This ensures that routes are primarily organized by their source patterns,
* with page-specific variations grouped together.
*
* @param a - First route to compare
* @param b - Second route to compare
* @returns Negative if route a should come first, positive if route b should come first, 0 if equal
*/
function compareSortableRoutes(a: SortableRoute, b: SortableRoute): number {
// First compare by source specificity - this is the primary sorting criterion
// Source represents the original route pattern and takes precedence
const sourceResult = compareRouteSegments(a.sourcePage, b.sourcePage)
if (sourceResult !== 0) return sourceResult
// If sources are identical, compare by page specificity as a tiebreaker
// Page represents the final rendered route and provides secondary ordering
return compareRouteSegments(a.page, b.page)
}
/**
* Sorts an array of routes by specificity using a deterministic depth-first traversal approach.
*
* This function implements Next.js route matching priority where more specific routes
* should be matched before less specific ones. The sorting is deterministic and stable,
* meaning identical inputs will always produce identical outputs.
*
* Sorting criteria (in order of priority):
* 1. Source path specificity (primary)
* 2. Page path specificity (secondary)
* 3. Lexicographic ordering (tertiary, for determinism)
*
* Examples of specificity order:
* - "/api/users" (static) comes before "/api/[slug]" (dynamic)
* - "/api/[id]" (dynamic) comes before "/api/[...slug]" (catch-all)
* - "/api/[...slug]" (catch-all) comes before "/api/[[...slug]]" (optional catch-all)
*
* @param routes - Array of routes to sort
* @returns New sorted array (does not mutate input)
*/
export function sortSortableRoutes(
routes: readonly SortableRoute[]
): readonly SortableRoute[] {
// Because sort is always in-place, we need to create a shallow copy to avoid
// mutating the input array.
return [...routes].sort(compareSortableRoutes)
}
/**
* Sorts an array of pages by specificity using a deterministic depth-first
* traversal approach.
*
* @param pages - Array of pages to sort
* @returns New sorted array (does not mutate input)
*/
export function sortPages(pages: readonly string[]): readonly string[] {
// Because sort is always in-place, we need to create a shallow copy to avoid
// mutating the input array.
return [...pages].sort(compareRouteSegments)
}
/**
* Sorts an array of objects by sourcePage and page using a deterministic
* depth-first traversal approach.
*
* @param objects - Array of objects to sort
* @param getter - Function to get the sourcePage and page from an object
* @returns New sorted array (does not mutate input)
*/
export function sortSortableRouteObjects<T>(
objects: readonly T[],
getter: (object: T) => SortableRoute
): readonly T[] {
// Create a SortableRoute for each object.
const routes: Array<SortableRoute & { object: T }> = []
for (const object of objects) {
const route = getter(object)
routes.push({ ...route, object })
}
// In-place sort the SortableRoutes.
routes.sort(compareSortableRoutes)
// Map the sorted SortableRoutes back to the original objects.
return routes.map(({ object }) => object)
}
/**
* Sorts an array of objects by page using a deterministic depth-first traversal
* approach.
*
* @param objects - Array of objects to sort
* @param getter - Function to get the page from an object
* @returns New sorted array (does not mutate input)
*/
export function sortPageObjects<T>(
objects: readonly T[],
getter: (object: T) => string
): readonly T[] {
const indexes: Record<string, number[]> = {}
const pages: Set<string> = new Set()
for (let i = 0; i < objects.length; i++) {
const object = objects[i]
const page = getter(object)
indexes[page]?.push(i) || (indexes[page] = [i])
pages.add(page)
}
// Sort the unique pages.
const sortedPages = Array.from(pages).sort(compareRouteSegments)
// Map the sorted pages back to the original objects.
return sortedPages.reduce<T[]>((sortedObjects, page) => {
// Add all objects for this page to the sorted array.
for (const i of indexes[page]) {
sortedObjects.push(objects[i])
}
// Return the sorted array.
return sortedObjects
}, [])
}
...@@ -201,6 +201,9 @@ class UrlNode { ...@@ -201,6 +201,9 @@ class UrlNode {
} }
} }
/**
* @deprecated Use `sortSortableRoutes` or `sortPages` instead.
*/
export function getSortedRoutes( export function getSortedRoutes(
normalizedPages: ReadonlyArray<string> normalizedPages: ReadonlyArray<string>
): string[] { ): string[] {
...@@ -223,6 +226,9 @@ export function getSortedRoutes( ...@@ -223,6 +226,9 @@ export function getSortedRoutes(
return root.smoosh() return root.smoosh()
} }
/**
* @deprecated Use `sortSortableRouteObjects` or `sortPageObjects` instead.
*/
export function getSortedRouteObjects<T>( export function getSortedRouteObjects<T>(
objects: T[], objects: T[],
getter: (obj: T) => string getter: (obj: T) => string
......
...@@ -4,8 +4,6 @@ import * as cheerio from 'cheerio' ...@@ -4,8 +4,6 @@ import * as cheerio from 'cheerio'
describe('sub-shell-generation', () => { describe('sub-shell-generation', () => {
const { next, isNextDev, isNextDeploy } = nextTestSetup({ const { next, isNextDev, isNextDeploy } = nextTestSetup({
files: __dirname, files: __dirname,
// FIXME: re-enable once we've re-enabled the sub-shell generation in Vercel
skipDeployment: true,
}) })
if (isNextDev) { if (isNextDev) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment