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
2de49121
Commit
2de49121
authored
Dec 09, 2025
by
Jiachi Liu
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
highlight reasons
parent
aef7c344
Show whitespace changes
Inline
Side-by-side
Showing
6 changed files
with
201 additions
and
46 deletions
+201
-46
suspense-boundary-injector.tsx
...next/src/server/app-render/suspense-boundary-injector.tsx
+48
-11
dynamic-rendering-utils.ts
packages/next/src/server/dynamic-rendering-utils.ts
+9
-0
params.ts
packages/next/src/server/request/params.ts
+16
-0
page.tsx
test/e2e/app-dir/suspense-profiling/app/dynamic/page.tsx
+65
-35
page.tsx
test/e2e/app-dir/suspense-profiling/app/item/[slug]/page.tsx
+61
-0
next.config.js
test/e2e/app-dir/suspense-profiling/next.config.js
+2
-0
No files found.
packages/next/src/server/app-render/suspense-boundary-injector.tsx
View file @
2de49121
...
@@ -57,9 +57,43 @@ const panelScript = `
...
@@ -57,9 +57,43 @@ const panelScript = `
}
}
};
};
// Match dynamic accesses to their enclosing suspense boundary
function matchDynamicToBoundary(boundaries, dynamicAccesses) {
var boundaryReasons = {}; // boundaryId -> [expressions]
dynamicAccesses.forEach(function(api) {
if (!api.frames.length) return;
var apiPath = api.frames.map(function(f) { return f.componentName; }).join('/');
// Find the boundary whose path is a prefix of the api path (nearest ancestor)
var bestMatch = null;
var bestMatchLen = 0;
boundaries.forEach(function(b) {
if (!b.frames.length) return;
var boundaryPath = b.frames.map(function(f) { return f.componentName; }).join('/');
// Check if boundary path is prefix of api path (or equal)
if (apiPath.indexOf(boundaryPath) === 0 && boundaryPath.length > bestMatchLen) {
bestMatch = b.id;
bestMatchLen = boundaryPath.length;
}
});
if (bestMatch) {
if (!boundaryReasons[bestMatch]) boundaryReasons[bestMatch] = [];
if (boundaryReasons[bestMatch].indexOf(api.expression) === -1) {
boundaryReasons[bestMatch].push(api.expression);
}
}
});
return boundaryReasons;
}
// Build tree from boundaries and dynamic accesses
// Build tree from boundaries and dynamic accesses
function buildTree(boundaries, dynamicAccesses) {
function buildTree(boundaries, dynamicAccesses
, boundaryReasons
) {
var root = { name: 'Root', children: {}, boundaries: [], apis: [] };
var root = { name: 'Root', children: {}, boundaries: [], apis: []
, reasons: []
};
// Add boundaries to tree
// Add boundaries to tree
boundaries.forEach(function(b) {
boundaries.forEach(function(b) {
...
@@ -70,11 +104,15 @@ const panelScript = `
...
@@ -70,11 +104,15 @@ const panelScript = `
path.forEach(function(frame) {
path.forEach(function(frame) {
var name = frame.componentName;
var name = frame.componentName;
if (!node.children[name]) {
if (!node.children[name]) {
node.children[name] = { name: name, children: {}, boundaries: [], apis: [], frame: frame };
node.children[name] = { name: name, children: {}, boundaries: [], apis: [],
reasons: [],
frame: frame };
}
}
node = node.children[name];
node = node.children[name];
});
});
node.boundaries.push(b);
node.boundaries.push(b);
// Attach reasons to this boundary node
if (boundaryReasons[b.id]) {
node.reasons = node.reasons.concat(boundaryReasons[b.id]);
}
});
});
// Add dynamic APIs to tree
// Add dynamic APIs to tree
...
@@ -85,7 +123,7 @@ const panelScript = `
...
@@ -85,7 +123,7 @@ const panelScript = `
path.forEach(function(frame) {
path.forEach(function(frame) {
var name = frame.componentName;
var name = frame.componentName;
if (!node.children[name]) {
if (!node.children[name]) {
node.children[name] = { name: name, children: {}, boundaries: [], apis: [], frame: frame };
node.children[name] = { name: name, children: {}, boundaries: [], apis: [],
reasons: [],
frame: frame };
}
}
node = node.children[name];
node = node.children[name];
});
});
...
@@ -106,10 +144,10 @@ const panelScript = `
...
@@ -106,10 +144,10 @@ const panelScript = `
if (depth > 0) {
if (depth > 0) {
var hasSuspense = node.boundaries.length > 0;
var hasSuspense = node.boundaries.length > 0;
var has
Apis = node.api
s.length > 0;
var has
Reasons = node.reasons && node.reason
s.length > 0;
html += '<div style="border-bottom:1px solid #f5f5f5;">';
html += '<div style="border-bottom:1px solid #f5f5f5;">';
html += '<div onclick="window.__sp.toggle(\\'' + path + '\\')" style="padding:8px 12px 8px ' + (12 + indent) + 'px;cursor:pointer;display:flex;align-items:center;gap:6px;">';
html += '<div onclick="window.__sp.toggle(\\'' + path + '\\')" style="padding:8px 12px 8px ' + (12 + indent) + 'px;cursor:pointer;display:flex;align-items:center;gap:6px;
flex-wrap:wrap;
">';
if (hasChildren) {
if (hasChildren) {
html += '<span style="color:#999;font-size:9px;width:10px;">' + (isExpanded ? '▼' : '▶') + '</span>';
html += '<span style="color:#999;font-size:9px;width:10px;">' + (isExpanded ? '▼' : '▶') + '</span>';
...
@@ -122,10 +160,8 @@ const panelScript = `
...
@@ -122,10 +160,8 @@ const panelScript = `
if (hasSuspense) {
if (hasSuspense) {
html += '<span style="background:#e8e8e8;color:#666;padding:1px 6px;border-radius:3px;font-size:10px;">suspense</span>';
html += '<span style="background:#e8e8e8;color:#666;padding:1px 6px;border-radius:3px;font-size:10px;">suspense</span>';
}
}
if (hasApis) {
if (hasReasons) {
var apiNames = [];
html += '<span style="color:#c41e3a;font-size:11px;margin-left:auto;">← ' + node.reasons.join(', ') + '</span>';
node.apis.forEach(function(a) { if (apiNames.indexOf(a.expression) === -1) apiNames.push(a.expression); });
html += '<span style="color:#888;font-size:11px;margin-left:auto;">' + apiNames.join(', ') + '</span>';
}
}
html += '</div></div>';
html += '</div></div>';
...
@@ -146,7 +182,8 @@ const panelScript = `
...
@@ -146,7 +182,8 @@ const panelScript = `
var sp = window.__sp;
var sp = window.__sp;
if (sp.isOpen) {
if (sp.isOpen) {
var tree = buildTree(boundaries, dynamicAccesses);
var boundaryReasons = matchDynamicToBoundary(boundaries, dynamicAccesses);
var tree = buildTree(boundaries, dynamicAccesses, boundaryReasons);
var treeHtml = '';
var treeHtml = '';
Object.keys(tree.children).forEach(function(key) {
Object.keys(tree.children).forEach(function(key) {
treeHtml += renderNode(tree.children[key], 1, key);
treeHtml += renderNode(tree.children[key], 1, key);
...
...
packages/next/src/server/dynamic-rendering-utils.ts
View file @
2de49121
import
type
{
NonStaticRenderStage
}
from
'./app-render/staged-rendering'
import
type
{
NonStaticRenderStage
}
from
'./app-render/staged-rendering'
import
type
{
RequestStore
}
from
'./app-render/work-unit-async-storage.external'
import
type
{
RequestStore
}
from
'./app-render/work-unit-async-storage.external'
import
React
from
'react'
import
{
trackDynamicAPIAccess
}
from
'./app-render/suspense-boundary-collector'
export
function
isHangingPromiseRejectionError
(
export
function
isHangingPromiseRejectionError
(
err
:
unknown
err
:
unknown
...
@@ -41,6 +43,13 @@ export function makeHangingPromise<T>(
...
@@ -41,6 +43,13 @@ export function makeHangingPromise<T>(
route
:
string
,
route
:
string
,
expression
:
string
expression
:
string
):
Promise
<
T
>
{
):
Promise
<
T
>
{
// Track the dynamic access for suspense profiling
const
ownerStack
=
process
.
env
.
NODE_ENV
!==
'production'
&&
React
.
captureOwnerStack
?
React
.
captureOwnerStack
()
:
null
trackDynamicAPIAccess
(
expression
,
ownerStack
)
if
(
signal
.
aborted
)
{
if
(
signal
.
aborted
)
{
return
Promise
.
reject
(
new
HangingPromiseRejectionError
(
route
,
expression
))
return
Promise
.
reject
(
new
HangingPromiseRejectionError
(
route
,
expression
))
}
else
{
}
else
{
...
...
packages/next/src/server/request/params.ts
View file @
2de49121
...
@@ -30,6 +30,8 @@ import {
...
@@ -30,6 +30,8 @@ import {
makeDevtoolsIOAwarePromise
,
makeDevtoolsIOAwarePromise
,
makeHangingPromise
,
makeHangingPromise
,
}
from
'../dynamic-rendering-utils'
}
from
'../dynamic-rendering-utils'
import
{
trackDynamicAPIAccess
}
from
'../app-render/suspense-boundary-collector'
import
React
from
'react'
import
{
createDedupedByCallsiteServerErrorLoggerDev
}
from
'../create-deduped-by-callsite-server-error-logger'
import
{
createDedupedByCallsiteServerErrorLoggerDev
}
from
'../create-deduped-by-callsite-server-error-logger'
import
{
dynamicAccessAsyncStorage
}
from
'../app-render/dynamic-access-async-storage.external'
import
{
dynamicAccessAsyncStorage
}
from
'../app-render/dynamic-access-async-storage.external'
import
{
RenderStage
}
from
'../app-render/staged-rendering'
import
{
RenderStage
}
from
'../app-render/staged-rendering'
...
@@ -528,6 +530,20 @@ function instrumentParamsPromiseWithDevWarnings(
...
@@ -528,6 +530,20 @@ function instrumentParamsPromiseWithDevWarnings(
warnForSyncAccess
(
workStore
.
route
,
expression
)
warnForSyncAccess
(
workStore
.
route
,
expression
)
}
}
}
}
// Track when params are awaited for suspense profiling
if
(
prop
===
'then'
)
{
const
originalThen
=
target
.
then
.
bind
(
target
)
return
function
(
onfulfilled
?:
((
value
:
Params
)
=>
any
)
|
null
,
onrejected
?:
((
reason
:
any
)
=>
any
)
|
null
)
{
const
ownerStack
=
React
.
captureOwnerStack
?
React
.
captureOwnerStack
()
:
null
trackDynamicAPIAccess
(
'`params`'
,
ownerStack
)
return
originalThen
(
onfulfilled
,
onrejected
)
}
}
return
ReflectAdapter
.
get
(
target
,
prop
,
receiver
)
return
ReflectAdapter
.
get
(
target
,
prop
,
receiver
)
},
},
set
(
target
,
prop
,
value
,
receiver
)
{
set
(
target
,
prop
,
value
,
receiver
)
{
...
...
test/e2e/app-dir/suspense-profiling/app/dynamic/page.tsx
View file @
2de49121
import
{
Suspense
}
from
'react'
import
{
Suspense
}
from
'react'
import
{
cookies
,
headers
}
from
'next/headers'
import
{
cookies
,
headers
}
from
'next/headers'
import
{
connection
}
from
'next/server'
// Component that uses cookies - triggers dynamic API
// =============================================================================
async
function
CookieCounter
()
{
// Case 1: cookies() - Request-specific data (no "use cache")
// =============================================================================
async
function
CookieContent
()
{
const
cookieStore
=
await
cookies
()
const
cookieStore
=
await
cookies
()
const
allCookies
=
cookieStore
.
getAll
()
const
allCookies
=
cookieStore
.
getAll
()
return
(
return
(
<
div
data
-
testid=
"cookie-co
unter
"
>
<
div
data
-
testid=
"cookie-co
ntent
"
>
Cookie count:
{
allCookies
.
length
}
Cookie count:
{
allCookies
.
length
}
</
div
>
</
div
>
)
)
}
}
// Component that uses headers - triggers dynamic API
// =============================================================================
async
function
HeaderInfo
()
{
// Case 2: headers() - Request-specific data (no "use cache")
// =============================================================================
async
function
HeaderContent
()
{
const
headersList
=
await
headers
()
const
headersList
=
await
headers
()
const
userAgent
=
headersList
.
get
(
'user-agent'
)
||
'Unknown'
const
userAgent
=
headersList
.
get
(
'user-agent'
)
||
'Unknown'
return
(
return
(
<
div
data
-
testid=
"header-
info
"
>
<
div
data
-
testid=
"header-
content
"
>
User Agent:
{
userAgent
.
slice
(
0
,
50
)
}
...
User Agent:
{
userAgent
.
slice
(
0
,
50
)
}
...
</
div
>
</
div
>
)
)
}
}
// Regular async component (no dynamic API)
// =============================================================================
async
function
SlowComponent
({
id
,
delay
}:
{
id
:
string
;
delay
:
number
})
{
// Case 3: connection() - Explicitly opt into dynamic rendering
await
new
Promise
((
resolve
)
=>
setTimeout
(
resolve
,
delay
))
// =============================================================================
return
<
div
data
-
testid=
{
`content-${id}`
}
>
Content
{
id
}
loaded
</
div
>
async
function
ConnectionContent
()
{
}
await
connection
()
// Wrapper components to make boundaries identifiable
function
CookieSection
()
{
return
(
return
(
<
Suspense
fallback=
{
<
div
data
-
testid=
"cookies-loading"
>
Loading cookies...
</
div
>
}
>
<
div
data
-
testid=
"connection-content"
>
<
CookieCounter
/>
Connection established at:
{
Date
.
now
()
}
</
Suspense
>
</
div
>
)
}
function
HeaderSection
()
{
return
(
<
Suspense
fallback=
{
<
div
data
-
testid=
"headers-loading"
>
Loading headers...
</
div
>
}
>
<
HeaderInfo
/>
</
Suspense
>
)
)
}
}
function
RegularSection
()
{
// =============================================================================
// Case 4: Static async content (for comparison)
// =============================================================================
async
function
StaticAsyncContent
()
{
await
new
Promise
((
resolve
)
=>
setTimeout
(
resolve
,
50
))
return
(
return
(
<
Suspense
fallback=
{
<
div
data
-
testid=
"regular-loading"
>
Loading regular...
</
div
>
}
>
<
div
data
-
testid=
"static-async-content"
>
<
SlowComponent
id=
"regular"
delay=
{
100
}
/>
This content is static async
</
Suspense
>
</
div
>
)
)
}
}
export
default
function
DynamicPage
()
{
export
default
function
DynamicPage
()
{
return
(
return
(
<
div
data
-
testid=
"dynamic-page-root"
>
<
div
data
-
testid=
"dynamic-page-root"
>
<
h1
>
Dynamic API Test
</
h1
>
<
h1
>
Dynamic API Test Cases
</
h1
>
<
p
>
These cases demonstrate dynamic APIs that trigger dynamic rendering.
</
p
>
<
section
>
<
section
>
<
h2
>
Dynamic APIs (will opt out of static rendering)
</
h2
>
<
h2
>
1. cookies() - Request cookies
</
h2
>
<
CookieSection
/>
<
Suspense
<
HeaderSection
/>
fallback=
{
<
div
data
-
testid=
"cookie-loading"
>
Loading cookies...
</
div
>
}
>
<
CookieContent
/>
</
Suspense
>
</
section
>
<
section
>
<
h2
>
2. headers() - Request headers
</
h2
>
<
Suspense
fallback=
{
<
div
data
-
testid=
"header-loading"
>
Loading headers...
</
div
>
}
>
<
HeaderContent
/>
</
Suspense
>
</
section
>
</
section
>
<
section
>
<
section
>
<
h2
>
Regular Async (no dynamic API)
</
h2
>
<
h2
>
3. connection() - Explicit dynamic opt-in
</
h2
>
<
RegularSection
/>
<
Suspense
fallback=
{
<
div
data
-
testid=
"connection-loading"
>
Loading connection...
</
div
>
}
>
<
ConnectionContent
/>
</
Suspense
>
</
section
>
<
section
>
<
h2
>
4. Static async content (for comparison)
</
h2
>
<
Suspense
fallback=
{
<
div
data
-
testid=
"static-async-loading"
>
Loading static...
</
div
>
}
>
<
StaticAsyncContent
/>
</
Suspense
>
</
section
>
</
section
>
</
div
>
</
div
>
)
)
...
...
test/e2e/app-dir/suspense-profiling/app/item/[slug]/page.tsx
0 → 100644
View file @
2de49121
import
{
Suspense
}
from
'react'
// Cached component that awaits params promise - triggers dynamic IO
async
function
DynamicContent
({
params
,
}:
{
params
:
Promise
<
{
slug
:
string
}
>
})
{
'use cache'
const
{
slug
}
=
await
params
await
new
Promise
((
resolve
)
=>
setTimeout
(
resolve
,
100
))
return
(
<
div
data
-
testid=
"dynamic-content"
>
<
p
>
Loaded content for:
{
slug
}
</
p
>
</
div
>
)
}
// Static cached content that doesn't depend on params
async
function
StaticHeader
()
{
'use cache'
return
(
<
header
data
-
testid=
"static-header"
>
<
h1
>
Item Details
</
h1
>
<
p
>
This header is static and can be prerendered
</
p
>
</
header
>
)
}
export
default
function
ItemPage
({
params
,
}:
{
params
:
Promise
<
{
slug
:
string
}
>
})
{
return
(
<
div
data
-
testid=
"item-page-root"
>
{
/* Static cached part - can be prerendered */
}
<
Suspense
fallback=
{
<
div
data
-
testid=
"header-loading"
>
Loading header...
</
div
>
}
>
<
StaticHeader
/>
</
Suspense
>
{
/* Dynamic part - params promise unpacked under Suspense boundary */
}
<
main
>
<
Suspense
fallback=
{
<
div
data
-
testid=
"param-loading"
>
Loading item details...
</
div
>
}
>
<
DynamicContent
params=
{
params
}
/>
</
Suspense
>
</
main
>
{
/* Another static section */
}
<
footer
data
-
testid=
"static-footer"
>
<
p
>
Static footer content
</
p
>
</
footer
>
</
div
>
)
}
test/e2e/app-dir/suspense-profiling/next.config.js
View file @
2de49121
/** @type {import('next').NextConfig} */
/** @type {import('next').NextConfig} */
module
.
exports
=
{
module
.
exports
=
{
cacheComponents
:
true
,
experimental
:
{
experimental
:
{
serverSourceMaps
:
true
,
suspenseProfiling
:
true
,
suspenseProfiling
:
true
,
},
},
}
}
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