Unverified Commit 96754b60 authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Tweaks to blocking route error message (#85191)

Makes it more clear that `<Suspense>` and "use cache" are separate
approaches for fixing the error, not requirements.

<img width="969" height="711" alt="Screenshot 2025-10-21 at 3 09 57 PM"
src="https://github.com/user-attachments/assets/34bd2efc-9fee-4aba-82eb-6b395663d765"
/>
parent 48bb490d
...@@ -67,22 +67,28 @@ function BlockingPageLoadErrorDescription() { ...@@ -67,22 +67,28 @@ function BlockingPageLoadErrorDescription() {
experience. Next.js uses this error to ensure your app loads instantly experience. Next.js uses this error to ensure your app loads instantly
on every navigation. on every navigation.
</p> </p>
<p>To fix this, you can:</p> <h4>To fix this, you can either:</h4>
<ul> <p className="nextjs__blocking_page_load_error_fix_option">
<li> <strong>Wrap the component in a {'<Suspense>'} boundary.</strong> This
Wrap the component in a {'<Suspense>'} boundary. This allows Next.js allows Next.js to stream its contents to the user as soon as it's ready,
to stream its contents to the user as soon as it's ready, without without blocking the rest of the app.
blocking the rest of the app. </p>
</li> <h4 className="nextjs__blocking_page_load_error_fix_option_separator">
<li> or
</h4>
<p className="nextjs__blocking_page_load_error_fix_option">
<strong>
Move the asynchronous await into a Cache Component ( Move the asynchronous await into a Cache Component (
<code>"use cache"</code>). This allows Next.js to statically prerender <code>"use cache"</code>)
the component as part of the HTML document, so it's instantly visible </strong>
to the user. Note that request-specific information &mdash; such as . This allows Next.js to statically prerender the component as part of
params, cookies, and headers &mdash; is not available during static the HTML document, so it's instantly visible to the user.
prerendering. </p>
</li> <p>
</ul> Note that request-specific information &mdash; such as params, cookies,
and headers &mdash; is not available during static prerendering, so must
be wrapped in {'<Suspense>'}.
</p>
<p> <p>
Learn more:{' '} Learn more:{' '}
<a href="https://nextjs.org/docs/messages/blocking-route"> <a href="https://nextjs.org/docs/messages/blocking-route">
...@@ -400,4 +406,10 @@ export const styles = ` ...@@ -400,4 +406,10 @@ export const styles = `
.nextjs__blocking_page_load_error_description_title { .nextjs__blocking_page_load_error_description_title {
color: var(--color-title-color); color: var(--color-title-color);
} }
.nextjs__blocking_page_load_error_fix_option {
background-color: var(--color-background-200);
padding: 14px;
border-radius: var(--rounded-md-2);
border: 1px solid var(--color-gray-alpha-400);
}
` `
...@@ -103,10 +103,15 @@ describe('Cache Components Dev Errors', () => { ...@@ -103,10 +103,15 @@ describe('Cache Components Dev Errors', () => {
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation.
To fix this, you can: To fix this, you can either:
Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app. Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user. Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering, so must be wrapped in <Suspense>.
Learn more: https://nextjs.org/docs/messages/blocking-route", Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
......
...@@ -160,10 +160,15 @@ describe('Cache Components Errors', () => { ...@@ -160,10 +160,15 @@ describe('Cache Components Errors', () => {
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation.
To fix this, you can: To fix this, you can either:
Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app. Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user. Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering, so must be wrapped in <Suspense>.
Learn more: https://nextjs.org/docs/messages/blocking-route", Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
...@@ -564,10 +569,15 @@ describe('Cache Components Errors', () => { ...@@ -564,10 +569,15 @@ describe('Cache Components Errors', () => {
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation.
To fix this, you can: To fix this, you can either:
Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app. Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user. Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering, so must be wrapped in <Suspense>.
Learn more: https://nextjs.org/docs/messages/blocking-route", Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
...@@ -587,10 +597,15 @@ describe('Cache Components Errors', () => { ...@@ -587,10 +597,15 @@ describe('Cache Components Errors', () => {
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation.
To fix this, you can: To fix this, you can either:
Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app. Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user. Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering, so must be wrapped in <Suspense>.
Learn more: https://nextjs.org/docs/messages/blocking-route", Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
...@@ -615,10 +630,15 @@ describe('Cache Components Errors', () => { ...@@ -615,10 +630,15 @@ describe('Cache Components Errors', () => {
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation.
To fix this, you can: To fix this, you can either:
Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app. Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user. Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering, so must be wrapped in <Suspense>.
Learn more: https://nextjs.org/docs/messages/blocking-route", Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
...@@ -638,10 +658,15 @@ describe('Cache Components Errors', () => { ...@@ -638,10 +658,15 @@ describe('Cache Components Errors', () => {
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation.
To fix this, you can: To fix this, you can either:
Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app. Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user. Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering, so must be wrapped in <Suspense>.
Learn more: https://nextjs.org/docs/messages/blocking-route", Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
...@@ -2068,10 +2093,15 @@ describe('Cache Components Errors', () => { ...@@ -2068,10 +2093,15 @@ describe('Cache Components Errors', () => {
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation.
To fix this, you can: To fix this, you can either:
Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app. Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user. Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering, so must be wrapped in <Suspense>.
Learn more: https://nextjs.org/docs/messages/blocking-route", Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
...@@ -2093,10 +2123,15 @@ describe('Cache Components Errors', () => { ...@@ -2093,10 +2123,15 @@ describe('Cache Components Errors', () => {
This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation. This delays the entire page from rendering, resulting in a slow user experience. Next.js uses this error to ensure your app loads instantly on every navigation.
To fix this, you can: To fix this, you can either:
Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app. Wrap the component in a <Suspense> boundary. This allows Next.js to stream its contents to the user as soon as it's ready, without blocking the rest of the app.
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user. Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering.
or
Move the asynchronous await into a Cache Component ("use cache"). This allows Next.js to statically prerender the component as part of the HTML document, so it's instantly visible to the user.
Note that request-specific information — such as params, cookies, and headers — is not available during static prerendering, so must be wrapped in <Suspense>.
Learn more: https://nextjs.org/docs/messages/blocking-route", Learn more: https://nextjs.org/docs/messages/blocking-route",
"environmentLabel": "Server", "environmentLabel": "Server",
......
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