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
3f821ad3
Commit
3f821ad3
authored
Apr 11, 2026
by
Jimmy Lai
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Collapse output export fallback critical path
parent
4abd51e4
Hide whitespace changes
Inline
Side-by-side
Showing
5 changed files
with
163 additions
and
26 deletions
+163
-26
output-export-fallback.test.ts
packages/next/src/client/output-export-fallback.test.ts
+54
-7
output-export-fallback.ts
packages/next/src/client/output-export-fallback.ts
+62
-15
output-export-fallback.ts
packages/next/src/export/helpers/output-export-fallback.ts
+5
-3
node-web-streams-helper.ts
...s/next/src/server/stream-utils/node-web-streams-helper.ts
+1
-1
dynamic-fallback-cache-components.test.ts
...dir-export/test/dynamic-fallback-cache-components.test.ts
+41
-0
No files found.
packages/next/src/client/output-export-fallback.test.ts
View file @
3f821ad3
...
...
@@ -11,9 +11,11 @@ import {
describe
(
'output export fallback helpers'
,
()
=>
{
const
originalFetch
=
global
.
fetch
const
originalTrailingSlash
=
process
.
env
.
__NEXT_TRAILING_SLASH
afterEach
(()
=>
{
global
.
fetch
=
originalFetch
process
.
env
.
__NEXT_TRAILING_SLASH
=
originalTrailingSlash
clearOutputExportFallbackManifestCache
()
jest
.
restoreAllMocks
()
})
...
...
@@ -91,7 +93,8 @@ describe('output export fallback helpers', () => {
])
})
it
(
'walks prefixes from the root until a fallback payload is found'
,
async
()
=>
{
it
(
'tries the direct fallback artifact before manifest lookups'
,
async
()
=>
{
process
.
env
.
__NEXT_TRAILING_SLASH
=
'false'
const
fetchMock
=
jest
.
fn
(
async
(
input
:
RequestInfo
|
URL
)
=>
{
const
url
=
String
(
input
)
...
...
@@ -102,10 +105,34 @@ describe('output export fallback helpers', () => {
})
}
return
new
Response
(
'not found'
,
{
status
:
404
,
headers
:
{
'content-type'
:
'text/html'
},
})
})
global
.
fetch
=
fetchMock
as
typeof
fetch
const
renderedUrl
=
new
URL
(
'https://example.com/org/acme/chat/123'
)
const
result
=
await
fetchOutputExportFallbackResponse
(
renderedUrl
)
expect
(
result
).
not
.
toBeNull
()
expect
(
result
?.
renderedUrl
.
href
).
toBe
(
renderedUrl
.
href
)
expect
(
fetchMock
.
mock
.
calls
.
map
(([
url
])
=>
String
(
url
))).
toEqual
([
'https://example.com/org/__fallback.txt'
,
])
})
it
(
'prefers the trailing-slash fallback artifact when the request URL ends with /'
,
async
()
=>
{
delete
process
.
env
.
__NEXT_TRAILING_SLASH
const
fetchMock
=
jest
.
fn
(
async
(
input
:
RequestInfo
|
URL
)
=>
{
const
url
=
String
(
input
)
if
(
url
.
endsWith
(
'/org/__fallback/index.txt'
))
{
return
new
Response
(
'
not found
'
,
{
status
:
404
,
headers
:
{
'content-type'
:
'text/
html
'
},
return
new
Response
(
'
flight
'
,
{
status
:
200
,
headers
:
{
'content-type'
:
'text/
x-component
'
},
})
}
...
...
@@ -117,21 +144,30 @@ describe('output export fallback helpers', () => {
global
.
fetch
=
fetchMock
as
typeof
fetch
const
renderedUrl
=
new
URL
(
'https://example.com/org/acme/chat/123'
)
const
renderedUrl
=
new
URL
(
'https://example.com/org/umbrella/chat/thread-789/'
)
const
result
=
await
fetchOutputExportFallbackResponse
(
renderedUrl
)
expect
(
result
).
not
.
toBeNull
()
expect
(
result
?.
renderedUrl
.
href
).
toBe
(
renderedUrl
.
href
)
expect
(
fetchMock
.
mock
.
calls
.
map
(([
url
])
=>
String
(
url
))).
toEqual
([
'https://example.com/org/__fallback.meta.json'
,
'https://example.com/org/__fallback.txt'
,
'https://example.com/org/__fallback/index.txt'
,
])
})
it
(
'uses fallback metadata to select the most specific conflicting route'
,
async
()
=>
{
process
.
env
.
__NEXT_TRAILING_SLASH
=
'false'
const
fetchMock
=
jest
.
fn
(
async
(
input
:
RequestInfo
|
URL
)
=>
{
const
url
=
String
(
input
)
if
(
url
.
endsWith
(
'/docs/__fallback.txt'
))
{
return
new
Response
(
'not found'
,
{
status
:
404
,
headers
:
{
'content-type'
:
'text/html'
},
})
}
if
(
url
.
endsWith
(
'/docs/__fallback.meta.json'
))
{
return
new
Response
(
JSON
.
stringify
({
...
...
@@ -175,12 +211,14 @@ describe('output export fallback helpers', () => {
expect
(
result
).
not
.
toBeNull
()
expect
(
result
?.
fallbackUrl
.
pathname
).
toBe
(
'/docs/__fallback/__route_0'
)
expect
(
fetchMock
.
mock
.
calls
.
map
(([
url
])
=>
String
(
url
))).
toEqual
([
'https://example.com/docs/__fallback.txt'
,
'https://example.com/docs/__fallback.meta.json'
,
'https://example.com/docs/__fallback/__route_0.txt'
,
])
})
it
(
'caches the resolved fallback data URL for later RSC fetches'
,
async
()
=>
{
process
.
env
.
__NEXT_TRAILING_SLASH
=
'false'
const
fetchMock
=
jest
.
fn
(
async
(
input
:
RequestInfo
|
URL
)
=>
{
const
url
=
String
(
input
)
...
...
@@ -247,9 +285,17 @@ describe('output export fallback helpers', () => {
})
it
(
'dedupes fallback artifact fetches across sibling routes'
,
async
()
=>
{
process
.
env
.
__NEXT_TRAILING_SLASH
=
'false'
const
fetchMock
=
jest
.
fn
(
async
(
input
:
RequestInfo
|
URL
)
=>
{
const
url
=
String
(
input
)
if
(
url
.
endsWith
(
'/docs/__fallback.txt'
))
{
return
new
Response
(
'not found'
,
{
status
:
404
,
headers
:
{
'content-type'
:
'text/html'
},
})
}
if
(
url
.
endsWith
(
'/docs/__fallback.meta.json'
))
{
return
new
Response
(
JSON
.
stringify
({
...
...
@@ -295,6 +341,7 @@ describe('output export fallback helpers', () => {
)
expect
(
fetchMock
.
mock
.
calls
.
map
(([
url
])
=>
String
(
url
))).
toEqual
([
'https://example.com/docs/__fallback.txt'
,
'https://example.com/docs/__fallback.meta.json'
,
'https://example.com/docs/__fallback/__route_0.txt'
,
])
...
...
packages/next/src/client/output-export-fallback.ts
View file @
3f821ad3
...
...
@@ -163,6 +163,22 @@ function getOutputExportDataCandidates(url: URL): URL[] {
return
[
direct
,
trailingSlash
]
}
function
getConfiguredOutputExportDataUrl
(
url
:
URL
,
prefersTrailingSlash
:
boolean
):
URL
{
const
trailingSlash
=
process
.
env
.
__NEXT_TRAILING_SLASH
const
configuredUrl
=
new
URL
(
url
)
const
useTrailingSlash
=
trailingSlash
==
null
?
prefersTrailingSlash
:
String
(
trailingSlash
)
===
'true'
if
(
useTrailingSlash
&&
!
configuredUrl
.
pathname
.
endsWith
(
'/'
))
{
configuredUrl
.
pathname
=
`
${
configuredUrl
.
pathname
}
/`
}
return
addOutputExportDataSuffix
(
configuredUrl
)
}
function
normalizeOutputExportRouteDirectory
(
pathname
:
string
):
string
{
if
(
pathname
===
'/'
)
{
return
''
...
...
@@ -229,6 +245,30 @@ async function fetchOutputExportDataResult(
return
null
}
async
function
fetchConfiguredOutputExportDataResult
(
renderedUrl
:
URL
,
prefersTrailingSlash
:
boolean
,
init
?:
RequestInit
):
Promise
<
{
response
:
Response
;
dataUrl
:
URL
}
|
null
>
{
const
configuredDataUrl
=
getConfiguredOutputExportDataUrl
(
renderedUrl
,
prefersTrailingSlash
)
const
response
=
await
fetchOutputExportDataResponseByUrl
(
configuredDataUrl
,
init
)
if
(
response
===
null
)
{
return
null
}
return
{
response
,
dataUrl
:
configuredDataUrl
,
}
}
async
function
fetchOutputExportDataResponseByUrl
(
dataUrl
:
URL
,
init
?:
RequestInit
...
...
@@ -287,12 +327,32 @@ export async function fetchOutputExportFallbackResponse(
renderedUrl
:
URL
,
init
?:
RequestInit
):
Promise
<
{
response
:
Response
;
renderedUrl
:
URL
;
fallbackUrl
:
URL
}
|
null
>
{
const
prefersTrailingSlash
=
renderedUrl
.
pathname
.
endsWith
(
'/'
)
for
(
const
candidate
of
getOutputExportFallbackCandidates
(
renderedUrl
.
pathname
))
{
const
candidateUrl
=
new
URL
(
renderedUrl
)
candidateUrl
.
pathname
=
candidate
const
directResult
=
await
fetchConfiguredOutputExportDataResult
(
candidateUrl
,
prefersTrailingSlash
,
init
)
if
(
directResult
)
{
cacheOutputExportFallbackDataUrl
(
renderedUrl
,
candidateUrl
,
directResult
.
dataUrl
)
return
{
response
:
directResult
.
response
,
renderedUrl
,
fallbackUrl
:
candidateUrl
,
}
}
const
fallbackManifest
=
await
fetchOutputExportFallbackManifest
(
candidateUrl
,
init
...
...
@@ -308,8 +368,9 @@ export async function fetchOutputExportFallbackResponse(
const
branchFallbackUrl
=
new
URL
(
renderedUrl
)
branchFallbackUrl
.
pathname
=
entry
.
fallbackPath
const
result
=
await
fetchOutputExportDataResult
(
const
result
=
await
fetch
Configured
OutputExportDataResult
(
branchFallbackUrl
,
prefersTrailingSlash
,
init
)
if
(
result
)
{
...
...
@@ -326,20 +387,6 @@ export async function fetchOutputExportFallbackResponse(
}
}
}
const
result
=
await
fetchOutputExportDataResult
(
candidateUrl
,
init
)
if
(
result
)
{
cacheOutputExportFallbackDataUrl
(
renderedUrl
,
candidateUrl
,
result
.
dataUrl
)
return
{
response
:
result
.
response
,
renderedUrl
,
fallbackUrl
:
candidateUrl
,
}
}
}
return
null
...
...
packages/next/src/export/helpers/output-export-fallback.ts
View file @
3f821ad3
...
...
@@ -286,9 +286,11 @@ export async function writeOutputExportFallbackHtml(
'<style id="
__next
-
export
-
fallback
-
style
">#__next{visibility:hidden}</style>'
const injection = `${exportFallbackStyle}${exportFallbackScript}`
const patchedFallbackHtml = fallbackHtml.includes('</head>')
? fallbackHtml.replace('</head>', `${injection}</head>`)
: injection + fallbackHtml
const patchedFallbackHtml = fallbackHtml.includes('<head>')
? fallbackHtml.replace('<head>', `<head>${injection}`)
: fallbackHtml.includes('</head>')
? fallbackHtml.replace('</head>', `${injection}</head>`)
: injection + fallbackHtml
await fs.writeFile(join(outDir, '_fallback.html'), patchedFallbackHtml)
}
...
...
packages/next/src/server/stream-utils/node-web-streams-helper.ts
View file @
3f821ad3
...
...
@@ -535,7 +535,7 @@ function createClientResumeScriptInsertionTransformStream(): TransformStream<
undefined
// headers[NEXT_URL]
)
const
searchStr
=
`
${
NEXT_RSC_UNION_QUERY
}
=
${
cacheBustingHeader
}
`
const
NEXT_CLIENT_RESUME_SCRIPT
=
`<script>try{var u=sessionStorage.getItem('
${
originalUrlSessionKey
}
');var r=location.pathname;if(u){r=r.endsWith('.html')?r.slice(0,-5)+'.txt':r.endsWith('/')?r+'index.txt':r+'.txt'}
__NEXT_CLIENT_RESUME=fetch(r+'?
${
searchStr
}
',{credentials:'same-origin',headers:{'
${
RSC_HEADER
}
': '1','
${
NEXT_ROUTER_PREFETCH_HEADER
}
': '1','
${
NEXT_ROUTER_SEGMENT_PREFETCH_HEADER
}
': '
${
segmentPath
}
'}});
if(u){window.
${
originalUrlGlobalKey
}
=u;history.replaceState(null,'',u);sessionStorage.removeItem('
${
originalUrlSessionKey
}
')}}catch{}</script>`
const
NEXT_CLIENT_RESUME_SCRIPT
=
`<script>try{var u=sessionStorage.getItem('
${
originalUrlSessionKey
}
');var r=location.pathname;if(u){r=r.endsWith('.html')?r.slice(0,-5)+'.txt':r.endsWith('/')?r+'index.txt':r+'.txt'}
if(!self.__NEXT_EXPORT_FALLBACK){__NEXT_CLIENT_RESUME=fetch(r+'?
${
searchStr
}
',{credentials:'same-origin',headers:{'
${
RSC_HEADER
}
': '1','
${
NEXT_ROUTER_PREFETCH_HEADER
}
': '1','
${
NEXT_ROUTER_SEGMENT_PREFETCH_HEADER
}
': '
${
segmentPath
}
'}})}
if(u){window.
${
originalUrlGlobalKey
}
=u;history.replaceState(null,'',u);sessionStorage.removeItem('
${
originalUrlSessionKey
}
')}}catch{}</script>`
let
didAlreadyInsert
=
false
return
new
TransformStream
({
...
...
test/e2e/app-dir-export/test/dynamic-fallback-cache-components.test.ts
View file @
3f821ad3
...
...
@@ -369,6 +369,47 @@ if (skipped) {
}
})
it
(
'loads nested fallback routes without concrete retries or extra probes'
,
async
()
=>
{
clearRequests
()
const
browser
=
await
webdriver
(
port
,
'/org/umbrella/chat/thread-789/'
)
try
{
await
retry
(
async
()
=>
{
expect
(
await
browser
.
elementByCss
(
'#org-name'
).
text
()).
toBe
(
'Org umbrella'
)
expect
(
await
browser
.
elementByCss
(
'h1'
).
text
()).
toBe
(
'umbrella:thread-789'
)
})
const
requests
=
getRequests
()
expect
(
requests
.
some
((
requestPath
)
=>
requestPath
.
startsWith
(
'/org/umbrella/chat/thread-789/?_rsc='
)
)
).
toBe
(
false
)
expect
(
requests
.
some
((
requestPath
)
=>
requestPath
.
startsWith
(
'/org/__fallback.meta.json'
)
)
).
toBe
(
false
)
expect
(
requests
.
some
((
requestPath
)
=>
requestPath
.
startsWith
(
'/org/__fallback.txt'
)
)
).
toBe
(
false
)
expect
(
requests
.
filter
((
requestPath
)
=>
requestPath
.
startsWith
(
'/org/__fallback/index.txt'
)
)
).
toHaveLength
(
1
)
}
finally
{
await
browser
.
close
()
}
})
it
(
'generates a hidden _fallback.html bootstrap document'
,
async
()
=>
{
const
outDir
=
join
(
next
.
testDir
,
'out'
)
const
fallbackHtml
=
await
fs
.
readFile
(
...
...
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