Skip to content
Projects
Groups
Snippets
Help
Loading...
Sign in
Toggle navigation
N
next.js
Project
Project
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Charts
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
Alex
next.js
Commits
3aa082ac
Commit
3aa082ac
authored
Jan 14, 2026
by
Zack Tanner
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
serve fallback shell when root params are unknown
parent
1d3554af
Show whitespace changes
Inline
Side-by-side
Showing
5 changed files
with
73 additions
and
70 deletions
+73
-70
index.ts
packages/next/src/build/index.ts
+7
-2
app.test.ts
packages/next/src/build/static-paths/app.test.ts
+4
-45
app.ts
packages/next/src/build/static-paths/app.ts
+19
-18
app-page.ts
packages/next/src/build/templates/app-page.ts
+12
-4
ppr-root-param-fallback.test.ts
...r/ppr-root-param-fallback/ppr-root-param-fallback.test.ts
+31
-1
No files found.
packages/next/src/build/index.ts
View file @
3aa082ac
...
@@ -3067,11 +3067,16 @@ export default async function build(
...
@@ -3067,11 +3067,16 @@ export default async function build(
// If the route has an empty static shell and is not configured to
// If the route has an empty static shell and is not configured to
// throw on empty static shell, then we should use the blocking
// throw on empty static shell, then we should use the blocking
// static render mode.
// static render mode. However, if the route has fallback root params,
// we preserve the PRERENDER mode to enable root param fallback shells.
if
(
if
(
hasEmptyStaticShell
&&
hasEmptyStaticShell
&&
!
route
.
throwOnEmptyStaticShell
&&
!
route
.
throwOnEmptyStaticShell
&&
route
.
fallbackMode
===
FallbackMode
.
PRERENDER
route
.
fallbackMode
===
FallbackMode
.
PRERENDER
&&
// Don't override to BLOCKING for routes with fallback root params,
// as we want to preserve the streaming behavior for root param
// fallback shells.
!
(
route
.
fallbackRootParams
&&
route
.
fallbackRootParams
.
length
>
0
)
)
{
)
{
return
FallbackMode
.
BLOCKING_STATIC_RENDER
return
FallbackMode
.
BLOCKING_STATIC_RENDER
}
}
...
...
packages/next/src/build/static-paths/app.test.ts
View file @
3aa082ac
...
@@ -1219,7 +1219,7 @@ describe('generateRouteStaticParams', () => {
...
@@ -1219,7 +1219,7 @@ describe('generateRouteStaticParams', () => {
describe('calculateFallbackMode', () => {
describe('calculateFallbackMode', () => {
it('should return NOT_FOUND when dynamic params are disabled', () => {
it('should return NOT_FOUND when dynamic params are disabled', () => {
const result = calculateFallbackMode(false,
[],
FallbackMode.PRERENDER)
const result = calculateFallbackMode(false, FallbackMode.PRERENDER)
expect(result).toBe(FallbackMode.NOT_FOUND)
expect(result).toBe(FallbackMode.NOT_FOUND)
})
})
...
@@ -1227,62 +1227,21 @@ describe('calculateFallbackMode', () => {
...
@@ -1227,62 +1227,21 @@ describe('calculateFallbackMode', () => {
it('should return NOT_FOUND when dynamic params are disabled regardless of root params', () => {
it('should return NOT_FOUND when dynamic params are disabled regardless of root params', () => {
const result = calculateFallbackMode(
const result = calculateFallbackMode(
false,
false,
['rootParam'],
FallbackMode.BLOCKING_STATIC_RENDER
FallbackMode.BLOCKING_STATIC_RENDER
)
)
expect(result).toBe(FallbackMode.NOT_FOUND)
expect(result).toBe(FallbackMode.NOT_FOUND)
})
})
it('should return BLOCKING_STATIC_RENDER when dynamic params are enabled and root params exist', () => {
it('should return base fallback mode when dynamic params are enabled', () => {
const result = calculateFallbackMode(
const result = calculateFallbackMode(true, FallbackMode.PRERENDER)
true,
['rootParam1', 'rootParam2'],
FallbackMode.PRERENDER
)
expect(result).toBe(FallbackMode.BLOCKING_STATIC_RENDER)
})
it('should return base fallback mode when dynamic params are enabled and no root params', () => {
const result = calculateFallbackMode(true, [], FallbackMode.PRERENDER)
expect(result).toBe(FallbackMode.PRERENDER)
expect(result).toBe(FallbackMode.PRERENDER)
})
})
it('should return base fallback mode when dynamic params are enabled and empty root params', () => {
const result = calculateFallbackMode(
true,
[],
FallbackMode.BLOCKING_STATIC_RENDER
)
expect(result).toBe(FallbackMode.BLOCKING_STATIC_RENDER)
})
it('should return NOT_FOUND when dynamic params are enabled but no base fallback mode provided', () => {
it('should return NOT_FOUND when dynamic params are enabled but no base fallback mode provided', () => {
const result = calculateFallbackMode(true,
[],
undefined)
const result = calculateFallbackMode(true, undefined)
expect(result).toBe(FallbackMode.NOT_FOUND)
expect(result).toBe(FallbackMode.NOT_FOUND)
})
})
it('should prioritize root params over base fallback mode', () => {
const result = calculateFallbackMode(
true,
['rootParam'],
FallbackMode.PRERENDER
)
expect(result).toBe(FallbackMode.BLOCKING_STATIC_RENDER)
})
it('should handle single root param correctly', () => {
const result = calculateFallbackMode(
true,
['singleParam'],
FallbackMode.PRERENDER
)
expect(result).toBe(FallbackMode.BLOCKING_STATIC_RENDER)
})
})
})
packages/next/src/build/static-paths/app.ts
View file @
3aa082ac
...
@@ -11,6 +11,7 @@ import path from 'node:path'
...
@@ -11,6 +11,7 @@ import path from 'node:path'
import
{
AfterRunner
}
from
'../../server/after/run-with-after'
import
{
AfterRunner
}
from
'../../server/after/run-with-after'
import
{
createWorkStore
}
from
'../../server/async-storage/work-store'
import
{
createWorkStore
}
from
'../../server/async-storage/work-store'
import
{
FallbackMode
}
from
'../../lib/fallback'
import
{
FallbackMode
}
from
'../../lib/fallback'
import
{
NEXT_QUERY_PARAM_PREFIX
}
from
'../../lib/constants'
import
type
{
IncrementalCache
}
from
'../../server/lib/incremental-cache'
import
type
{
IncrementalCache
}
from
'../../server/lib/incremental-cache'
import
{
import
{
normalizePathname
,
normalizePathname
,
...
@@ -283,15 +284,17 @@ export function generateAllParamCombinations(
...
@@ -283,15 +284,17 @@ export function generateAllParamCombinations(
*/
*/
export
function
calculateFallbackMode
(
export
function
calculateFallbackMode
(
dynamicParams
:
boolean
,
dynamicParams
:
boolean
,
fallbackRootParams
:
readonly
string
[],
baseFallbackMode
:
FallbackMode
|
undefined
baseFallbackMode
:
FallbackMode
|
undefined
):
FallbackMode
{
):
FallbackMode
{
// When dynamicParams is enabled, use the base fallback mode to allow fallback
// shells to be served. Previously this forced BLOCKING_STATIC_RENDER when
// root params were unknown, but that prevented reuse of fallback shells
// across different requests with the same root param value.
//
// The fallbackRootParams are still tracked and included in cache keys to
// ensure each unique root param value gets its own cached content.
return
dynamicParams
return
dynamicParams
?
// If the fallback params includes any root params, then we need to
?
(
baseFallbackMode
??
FallbackMode
.
NOT_FOUND
)
// perform a blocking static render.
fallbackRootParams
.
length
>
0
?
FallbackMode
.
BLOCKING_STATIC_RENDER
:
(
baseFallbackMode
??
FallbackMode
.
NOT_FOUND
)
:
FallbackMode
.
NOT_FOUND
:
FallbackMode
.
NOT_FOUND
}
}
...
@@ -881,12 +884,12 @@ export async function buildAppStaticPaths({
...
@@ -881,12 +884,12 @@ export async function buildAppStaticPaths({
pathname
:
page
,
pathname
:
page
,
encodedPathname
:
page
,
encodedPathname
:
page
,
fallbackRouteParams
,
fallbackRouteParams
,
fallbackMode
:
calculateFallbackMode
(
fallbackMode
:
calculateFallbackMode
(
dynamicParams
,
fallbackMode
),
dynamicParams
,
// Prefix root param keys with NEXT_QUERY_PARAM_PREFIX to match the
rootParamKeys
,
// format used in routeKeys for allowQuery cache key variation.
fallbackMode
fallbackRootParams
:
rootParamKeys
.
map
(
(
key
)
=>
`
${
NEXT_QUERY_PARAM_PREFIX
}${
key
}
`
),
),
fallbackRootParams
:
rootParamKeys
,
throwOnEmptyStaticShell
:
true
,
throwOnEmptyStaticShell
:
true
,
})
})
}
}
...
@@ -968,9 +971,11 @@ export async function buildAppStaticPaths({
...
@@ -968,9 +971,11 @@ export async function buildAppStaticPaths({
const
fallbackRootParams
:
string
[]
=
[]
const
fallbackRootParams
:
string
[]
=
[]
for
(
const
{
paramName
}
of
fallbackRouteParams
)
{
for
(
const
{
paramName
}
of
fallbackRouteParams
)
{
// If the param is a root param then we can add it to the fallback
// If the param is a root param then we can add it to the fallback
// root params.
// root params. We prefix with NEXT_QUERY_PARAM_PREFIX to match the
// format used in routeKeys, which is what the proxy expects for
// allowQuery cache key variation.
if
(
rootParamSet
.
has
(
paramName
))
{
if
(
rootParamSet
.
has
(
paramName
))
{
fallbackRootParams
.
push
(
paramName
)
fallbackRootParams
.
push
(
`
${
NEXT_QUERY_PARAM_PREFIX
}${
paramName
}
`
)
}
}
}
}
...
@@ -981,11 +986,7 @@ export async function buildAppStaticPaths({
...
@@ -981,11 +986,7 @@ export async function buildAppStaticPaths({
pathname
,
pathname
,
encodedPathname
:
normalizePathname
(
encodedPathname
),
encodedPathname
:
normalizePathname
(
encodedPathname
),
fallbackRouteParams
,
fallbackRouteParams
,
fallbackMode
:
calculateFallbackMode
(
fallbackMode
:
calculateFallbackMode
(
dynamicParams
,
fallbackMode
),
dynamicParams
,
fallbackRootParams
,
fallbackMode
),
fallbackRootParams
,
fallbackRootParams
,
throwOnEmptyStaticShell
:
true
,
throwOnEmptyStaticShell
:
true
,
})
})
...
...
packages/next/src/build/templates/app-page.ts
View file @
3aa082ac
...
@@ -912,15 +912,16 @@ export async function handler(
...
@@ -912,15 +912,16 @@ export async function handler(
isFallback
:
true
,
isFallback
:
true
,
prerenderManifest
,
prerenderManifest
,
isRoutePPREnabled
,
isRoutePPREnabled
,
responseGenerator
:
async
()
=>
responseGenerator
:
async
()
=>
{
doRender
({
return
doRender
({
span
,
span
,
// We pass `undefined` as rendering a fallback isn't resumed
// We pass `undefined` as rendering a fallback isn't resumed
// here.
// here.
postponed
:
undefined
,
postponed
:
undefined
,
fallbackRouteParams
,
fallbackRouteParams
,
forceStaticRender
:
false
,
forceStaticRender
:
false
,
}),
})
},
waitUntil
:
ctx
.
waitUntil
,
waitUntil
:
ctx
.
waitUntil
,
isMinimalMode
,
isMinimalMode
,
})
})
...
@@ -1052,13 +1053,20 @@ export async function handler(
...
@@ -1052,13 +1053,20 @@ export async function handler(
}
}
}
}
// Determine if we should use fallback route params for rendering.
// This is used to render a fallback shell with placeholder params.
const
shouldRenderFallbackShell
=
getRequestMeta
(
req
,
'renderFallbackShell'
)
const
fallbackRouteParams
=
const
fallbackRouteParams
=
// If we're in production and we have fallback route params, then we
// If we're in production and we have fallback route params, then we
// can use the manifest fallback route params if we need to render the
// can use the manifest fallback route params if we need to render the
// fallback shell.
// fallback shell.
isProduction
&&
isProduction
&&
prerenderInfo
?.
fallbackRouteParams
&&
prerenderInfo
?.
fallbackRouteParams
&&
getRequestMeta
(
req
,
'renderFallbackShell'
)
shouldRenderFallbackShell
?
createOpaqueFallbackRouteParams
(
prerenderInfo
.
fallbackRouteParams
)
?
createOpaqueFallbackRouteParams
(
prerenderInfo
.
fallbackRouteParams
)
:
// Otherwise, if we're debugging the fallback shell, then we have to
:
// Otherwise, if we're debugging the fallback shell, then we have to
// manually generate the fallback route params.
// manually generate the fallback route params.
...
...
test/e2e/app-dir/ppr-root-param-fallback/ppr-root-param-fallback.test.ts
View file @
3aa082ac
import
{
nextTestSetup
}
from
'e2e-utils'
import
{
nextTestSetup
}
from
'e2e-utils'
describe
(
'ppr-root-param-fallback'
,
()
=>
{
describe
(
'ppr-root-param-fallback'
,
()
=>
{
const
{
next
}
=
nextTestSetup
({
const
{
next
,
isNextDev
}
=
nextTestSetup
({
files
:
__dirname
,
files
:
__dirname
,
})
})
if
(
isNextDev
)
{
it
(
'should skip in dev mode'
,
()
=>
{})
return
}
it
(
'should have use-cache content in fallback shells for all pregenerated locales'
,
async
()
=>
{
it
(
'should have use-cache content in fallback shells for all pregenerated locales'
,
async
()
=>
{
// Setup: The app has a [locale] param with generateStaticParams returning
// Setup: The app has a [locale] param with generateStaticParams returning
// ['en', 'fr'], and a nested /[locale]/blog/[slug] route. The layout uses
// ['en', 'fr'], and a nested /[locale]/blog/[slug] route. The layout uses
...
@@ -27,4 +32,29 @@ describe('ppr-root-param-fallback', () => {
...
@@ -27,4 +32,29 @@ describe('ppr-root-param-fallback', () => {
expect
(
$
(
'#locale-loading'
).
length
).
toBe
(
0
)
expect
(
$
(
'#locale-loading'
).
length
).
toBe
(
0
)
}
}
})
})
it
(
'should serve a fallback shell for non-pregenerated root param values'
,
async
()
=>
{
// Setup: The app only pregenerates locales ['en', 'fr']
//
// When visiting a non-prerendered root param, we should still serve a fallback shell
// and resume with the missing data.
// Check the raw HTML response - it should contain the loading fallback,
// proving we got a streamed fallback shell (not a blocking render)
const
$
=
await
next
.
render$
(
'/de/blog/new-post'
)
expect
(
$
(
'#blog-loading'
).
length
).
toBe
(
1
)
expect
(
$
(
'#blog-loading'
).
text
()).
toBe
(
'Loading article...'
)
// Use the browser to verify the final state after streaming/hydration
const
browser
=
await
next
.
browser
(
'/de/blog/new-post'
)
// The loading state should be gone after streaming completes
const
loadingElements
=
await
browser
.
elementsByCss
(
'#blog-loading'
)
expect
(
loadingElements
.
length
).
toBe
(
0
)
// The final content should be present with the correct locale and slug
const
content
=
await
browser
.
waitForElementByCss
(
'#blog-content'
).
text
()
expect
(
content
).
toContain
(
'de'
)
expect
(
content
).
toContain
(
'new-post'
)
})
})
})
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment