From 3e92e34cba4b0069c5bf9179cb8cf58b47c05262 Mon Sep 17 00:00:00 2001
From: Joseph Chamochumbi <joseph.chamochumbi@vercel.com>
Date: Thu, 6 Aug 2026 17:44:08 +0200
Subject: [PATCH 1/3] docs: Suspense boundaries can hold content back on size,
 not just slow data

---
 docs/01-app/02-guides/streaming.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/01-app/02-guides/streaming.mdx b/docs/01-app/02-guides/streaming.mdx
index a25bbaea0490..d74608aee9fd 100644
--- a/docs/01-app/02-guides/streaming.mdx
+++ b/docs/01-app/02-guides/streaming.mdx
@@ -36,7 +36,7 @@ When a browser requests a page, two streams work together during the initial pag
 
 ### The HTML stream
 
-React's server renderer produces progressive HTML chunks. The static parts of your page (layouts, navigation, Suspense fallbacks) render first and are sent immediately. When an async [Server Component](/docs/app/glossary#server-component) resolves, React streams its completed HTML along with inline `<script>` tags: one that swaps the fallback DOM node with the new content, and another carrying the [component payload](#the-component-payload) so React can later hydrate it. The browser executes the swap instantly, without waiting for the page's JavaScript bundle to load or hydration to complete. This is what the user _sees_: the page painting progressively, section by section.
+React's server renderer produces progressive HTML chunks. The static parts of your page (layouts, navigation, Suspense fallbacks) render first and are sent immediately. When a `<Suspense>` boundary's content is ready, for example when an async [Server Component](/docs/app/glossary#server-component) resolves, React streams its completed HTML along with inline `<script>` tags: one that swaps the fallback DOM node with the new content, and another carrying the [component payload](#the-component-payload) so React can later hydrate it. The browser executes the swap instantly, without waiting for the page's JavaScript bundle to load or hydration to complete. This is what the user _sees_: the page painting progressively, section by section.
 
 ### The component payload
 
@@ -579,11 +579,11 @@ Without streaming, the server waits for all data before sending any HTML, so TTF
 
 ### LCP (Largest Contentful Paint)
 
-If your LCP element (a hero image, a main heading, a product photo) is inside a Suspense boundary, it can't paint until that boundary resolves. To keep LCP fast:
+If your LCP element (a hero image, a main heading, a product photo) is inside a Suspense boundary, it can't paint until that boundary's content is swapped in. This isn't limited to boundaries waiting on slow data: React can also hold a boundary back when it has enough content, whether or not anything inside it suspended. See [what activates a Suspense boundary](https://react.dev/reference/react/Suspense#what-activates-a-suspense-boundary). To keep LCP fast:
 
 - Keep LCP elements **outside** or **above** Suspense boundaries so they render as part of the static shell.
-- Use the [`preload`](/docs/app/api-reference/components/image#preload) prop on `next/image` for LCP images. This injects a `<link rel="preload">` into the `<head>`, so the browser starts fetching the image from the very first chunk, before the `<img>` tag even appears in the HTML.
-- For non-image LCP elements (text, headings), make sure they are not wrapped in a Suspense boundary that depends on slow data.
+- Use the [`preload`](/docs/app/api-reference/components/image#preload) prop on `next/image` for LCP images. This injects a `<link rel="preload">` into the `<head>`, so the browser starts fetching the image from the very first chunk, before the `<img>` tag even appears in the HTML. It controls when the image is fetched, not when it paints: an image inside a boundary still waits for the swap.
+- For non-image LCP elements (text, headings), make sure they are not wrapped in a Suspense boundary.
 
 ### CLS (Cumulative Layout Shift)
 

From c1a97b8c5916c095306899b254d3eb88c828c03d Mon Sep 17 00:00:00 2001
From: Joseph Chamochumbi <joseph.chamochumbi@vercel.com>
Date: Fri, 7 Aug 2026 22:07:07 +0200
Subject: [PATCH 2/3] docs: clarify why a Suspense boundary delays LCP

The LCP element stops depending on initial server response time and
starts depending on the server's render work plus the browser running
the streamed swap script. Add a rule of thumb about not adding
boundaries you don't need.
---
 docs/01-app/02-guides/streaming.mdx | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/01-app/02-guides/streaming.mdx b/docs/01-app/02-guides/streaming.mdx
index d74608aee9fd..02d2cc92ec33 100644
--- a/docs/01-app/02-guides/streaming.mdx
+++ b/docs/01-app/02-guides/streaming.mdx
@@ -579,7 +579,13 @@ Without streaming, the server waits for all data before sending any HTML, so TTF
 
 ### LCP (Largest Contentful Paint)
 
-If your LCP element (a hero image, a main heading, a product photo) is inside a Suspense boundary, it can't paint until that boundary's content is swapped in. This isn't limited to boundaries waiting on slow data: React can also hold a boundary back when it has enough content, whether or not anything inside it suspended. See [what activates a Suspense boundary](https://react.dev/reference/react/Suspense#what-activates-a-suspense-boundary). To keep LCP fast:
+If your LCP element (a hero image, a main heading, a product photo) is inside a Suspense boundary, it can't paint until that boundary's content is swapped in. This is fundamentally a problem because the LCP element no longer depends on your initial server response time, but on the server and the work it does to eventually render that element, plus the browser's own work to reveal it: React streams a small inline script alongside the boundary's HTML, and the content is only on screen once that script runs.
+
+Data fetching is not the only reason an LCP element might not render immediately. A boundary with enough HTML is held back on size alone, because sending that HTML takes time. See [what activates a Suspense boundary](https://react.dev/reference/react/Suspense#what-activates-a-suspense-boundary).
+
+> **Good to know:** As a rule of thumb, if there's a Suspense boundary, React might use it. Under a slow network or a busy CPU, concurrent rendering can fall back to it even when you didn't expect it. Adding a boundary means accepting that, so don't add one you don't need.
+
+To keep LCP fast:
 
 - Keep LCP elements **outside** or **above** Suspense boundaries so they render as part of the static shell.
 - Use the [`preload`](/docs/app/api-reference/components/image#preload) prop on `next/image` for LCP images. This injects a `<link rel="preload">` into the `<head>`, so the browser starts fetching the image from the very first chunk, before the `<img>` tag even appears in the HTML. It controls when the image is fetched, not when it paints: an image inside a boundary still waits for the swap.

From 5c5fc195efe030184f5d5ea9a6c804c483a504b4 Mon Sep 17 00:00:00 2001
From: Joseph Chamochumbi <joseph.chamochumbi@vercel.com>
Date: Fri, 7 Aug 2026 22:28:25 +0200
Subject: [PATCH 3/3] docs: tighten LCP streaming wording

Split the comma-heavy sentence, drop mid-sentence colons and the bare
'this' subject, and flip the non-image bullet to positive phrasing.
---
 docs/01-app/02-guides/streaming.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/01-app/02-guides/streaming.mdx b/docs/01-app/02-guides/streaming.mdx
index 02d2cc92ec33..4f65f0a32b0e 100644
--- a/docs/01-app/02-guides/streaming.mdx
+++ b/docs/01-app/02-guides/streaming.mdx
@@ -579,17 +579,17 @@ Without streaming, the server waits for all data before sending any HTML, so TTF
 
 ### LCP (Largest Contentful Paint)
 
-If your LCP element (a hero image, a main heading, a product photo) is inside a Suspense boundary, it can't paint until that boundary's content is swapped in. This is fundamentally a problem because the LCP element no longer depends on your initial server response time, but on the server and the work it does to eventually render that element, plus the browser's own work to reveal it: React streams a small inline script alongside the boundary's HTML, and the content is only on screen once that script runs.
+If your LCP element (a hero image, a main heading, a product photo) is inside a Suspense boundary, it can't paint until that boundary's content is swapped in. The element then depends on the work the server does to render it, not on your initial server response time. Revealing it costs something on the client too, because React streams a small inline script alongside the boundary's HTML and the content only appears once that script runs.
 
-Data fetching is not the only reason an LCP element might not render immediately. A boundary with enough HTML is held back on size alone, because sending that HTML takes time. See [what activates a Suspense boundary](https://react.dev/reference/react/Suspense#what-activates-a-suspense-boundary).
+Data fetching is not the only reason a boundary delays your LCP element. React also holds back a large boundary, because sending its HTML takes time. See [what activates a Suspense boundary](https://react.dev/reference/react/Suspense#what-activates-a-suspense-boundary).
 
 > **Good to know:** As a rule of thumb, if there's a Suspense boundary, React might use it. Under a slow network or a busy CPU, concurrent rendering can fall back to it even when you didn't expect it. Adding a boundary means accepting that, so don't add one you don't need.
 
 To keep LCP fast:
 
 - Keep LCP elements **outside** or **above** Suspense boundaries so they render as part of the static shell.
-- Use the [`preload`](/docs/app/api-reference/components/image#preload) prop on `next/image` for LCP images. This injects a `<link rel="preload">` into the `<head>`, so the browser starts fetching the image from the very first chunk, before the `<img>` tag even appears in the HTML. It controls when the image is fetched, not when it paints: an image inside a boundary still waits for the swap.
-- For non-image LCP elements (text, headings), make sure they are not wrapped in a Suspense boundary.
+- Use the [`preload`](/docs/app/api-reference/components/image#preload) prop on `next/image` for LCP images. This injects a `<link rel="preload">` into the `<head>`, so the browser starts fetching the image from the very first chunk, before the `<img>` tag even appears in the HTML. It controls when the image is fetched, not when it paints. An image inside a boundary still waits for the swap.
+- For non-image LCP elements (text, headings), render them outside Suspense boundaries.
 
 ### CLS (Cumulative Layout Shift)
 
