Commit 3aa082ac authored by Zack Tanner's avatar Zack Tanner

serve fallback shell when root params are unknown

parent 1d3554af
......@@ -3067,11 +3067,16 @@ export default async function build(
// If the route has an empty static shell and is not configured to
// 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 (
hasEmptyStaticShell &&
!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
}
......
......@@ -1219,7 +1219,7 @@ describe('generateRouteStaticParams', () => {
describe('calculateFallbackMode', () => {
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)
})
......@@ -1227,62 +1227,21 @@ describe('calculateFallbackMode', () => {
it('should return NOT_FOUND when dynamic params are disabled regardless of root params', () => {
const result = calculateFallbackMode(
false,
['rootParam'],
FallbackMode.BLOCKING_STATIC_RENDER
)
expect(result).toBe(FallbackMode.NOT_FOUND)
})
it('should return BLOCKING_STATIC_RENDER when dynamic params are enabled and root params exist', () => {
const result = calculateFallbackMode(
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)
it('should return base fallback mode when dynamic params are enabled', () => {
const result = calculateFallbackMode(true, 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', () => {
const result = calculateFallbackMode(true, [], undefined)
const result = calculateFallbackMode(true, undefined)
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)
})
})
......@@ -11,6 +11,7 @@ import path from 'node:path'
import { AfterRunner } from '../../server/after/run-with-after'
import { createWorkStore } from '../../server/async-storage/work-store'
import { FallbackMode } from '../../lib/fallback'
import { NEXT_QUERY_PARAM_PREFIX } from '../../lib/constants'
import type { IncrementalCache } from '../../server/lib/incremental-cache'
import {
normalizePathname,
......@@ -283,15 +284,17 @@ export function generateAllParamCombinations(
*/
export function calculateFallbackMode(
dynamicParams: boolean,
fallbackRootParams: readonly string[],
baseFallbackMode: FallbackMode | undefined
): 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
? // If the fallback params includes any root params, then we need to
// perform a blocking static render.
fallbackRootParams.length > 0
? FallbackMode.BLOCKING_STATIC_RENDER
: (baseFallbackMode ?? FallbackMode.NOT_FOUND)
? (baseFallbackMode ?? FallbackMode.NOT_FOUND)
: FallbackMode.NOT_FOUND
}
......@@ -881,12 +884,12 @@ export async function buildAppStaticPaths({
pathname: page,
encodedPathname: page,
fallbackRouteParams,
fallbackMode: calculateFallbackMode(
dynamicParams,
rootParamKeys,
fallbackMode
fallbackMode: calculateFallbackMode(dynamicParams, fallbackMode),
// Prefix root param keys with NEXT_QUERY_PARAM_PREFIX to match the
// format used in routeKeys for allowQuery cache key variation.
fallbackRootParams: rootParamKeys.map(
(key) => `${NEXT_QUERY_PARAM_PREFIX}${key}`
),
fallbackRootParams: rootParamKeys,
throwOnEmptyStaticShell: true,
})
}
......@@ -968,9 +971,11 @@ export async function buildAppStaticPaths({
const fallbackRootParams: string[] = []
for (const { paramName } of fallbackRouteParams) {
// 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)) {
fallbackRootParams.push(paramName)
fallbackRootParams.push(`${NEXT_QUERY_PARAM_PREFIX}${paramName}`)
}
}
......@@ -981,11 +986,7 @@ export async function buildAppStaticPaths({
pathname,
encodedPathname: normalizePathname(encodedPathname),
fallbackRouteParams,
fallbackMode: calculateFallbackMode(
dynamicParams,
fallbackRootParams,
fallbackMode
),
fallbackMode: calculateFallbackMode(dynamicParams, fallbackMode),
fallbackRootParams,
throwOnEmptyStaticShell: true,
})
......
......@@ -912,15 +912,16 @@ export async function handler(
isFallback: true,
prerenderManifest,
isRoutePPREnabled,
responseGenerator: async () =>
doRender({
responseGenerator: async () => {
return doRender({
span,
// We pass `undefined` as rendering a fallback isn't resumed
// here.
postponed: undefined,
fallbackRouteParams,
forceStaticRender: false,
}),
})
},
waitUntil: ctx.waitUntil,
isMinimalMode,
})
......@@ -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 =
// 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
// fallback shell.
isProduction &&
prerenderInfo?.fallbackRouteParams &&
getRequestMeta(req, 'renderFallbackShell')
shouldRenderFallbackShell
? createOpaqueFallbackRouteParams(prerenderInfo.fallbackRouteParams)
: // Otherwise, if we're debugging the fallback shell, then we have to
// manually generate the fallback route params.
......
import { nextTestSetup } from 'e2e-utils'
describe('ppr-root-param-fallback', () => {
const { next } = nextTestSetup({
const { next, isNextDev } = nextTestSetup({
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 () => {
// Setup: The app has a [locale] param with generateStaticParams returning
// ['en', 'fr'], and a nested /[locale]/blog/[slug] route. The layout uses
......@@ -27,4 +32,29 @@ describe('ppr-root-param-fallback', () => {
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')
})
})
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