Suspense Around Static Content Still Shifts the Layout: Fixing CLS on a Prebuilt Next.js 16 Site
Suspense Around Static Content Still Shifts the Layout: Fixing CLS on a Prebuilt Next.js 16 Site
Why wrapping already-prebuilt blocks in Suspense still caused 0.999 CLS on Next.js 16, and the shell-level regression…
·Updated on:··
⚡ Next.js Implementation Guides
In-depth Next.js guides covering App Router, RSC, ISR, and deployment. Get code examples, optimization checklists, and prompts to accelerate development.
By Matija, the developer behind Build with Matija. In mid-November 2026 I was taking a large bilingual marketing and product site, migrated from WordPress to Payload CMS, through its performance pass before launch. Every public page is prebuilt at build time. This article is written from the PageSpeed, Lighthouse and Playwright reports of that pass and from the fixes that went into the site between 13 and 15 November. Versions: Next.js 16 (App Router, Cache Components), React 19.2, Payload 3.93, Lighthouse 12.8 locally and 13.6 on PageSpeed Insights. Last updated 2026-11-16.
A Suspense boundary around content that never suspends can still shift your layout. In the prerendered HTML, React may write a large finished boundary out of the visible page shell into a hidden segment further down the stream, and swap it in after the first paint. Everything below it moves. On one site this produced a cumulative layout shift (CLS) of 0.999 on the product page and 0.24 to 0.51 on six listing and hub pages, even though every one of those pages was fully static and some boundaries had carefully sized skeletons. The fix was to remove Suspense from every block that has nothing to wait for, keep the error boundary, and add a script that fails a URL when its shell HTML still has a hole above the fold.
The advice that was not enough
The usual Next.js advice on layout shift, including mine, is about fallbacks. In the use cache migration guide I wrote that fallback={null} reserves no space and that a skeleton should match the final component's size. In the static shell pattern guide and the Partial Prerendering guide, the model is: static and cached work goes into the shell, request-time work goes behind Suspense, and the fallback holds its place.
All of that is still true for content that really waits. It misses a second case: content that is already finished at build time but sits inside a <Suspense> anyway, because a shared wrapper put it there. The migration guide's table says data behind 'use cache' "can be computed and included in the static shell". On this site it was computed and it was in the HTML, but not where the browser paints first.
What the HTML actually contained
The site renders Payload layout blocks through one shared component, BlockBoundary. It combined an error boundary with a Suspense boundary and an optional skeleton, so that one broken block could not take down the page. Every block got it, including blocks that do no async work at all: the product hero, the product detail accordions, the list hero on recipes, blog and events, the taxonomy grids on the hub pages, and the store locator band.
When I read the raw HTML of a prebuilt product page, the hero was not in the shell. The shell had a placeholder:
html
<!-- in the shell, where the hero should be --><templateid="B:2"></template><!-- much later in the same response --><divhiddenid="S:2"> ...about 38 KB of finished hero markup... </div><>
React's streaming renderer had treated the finished boundary as a separate segment: it wrote a <template id="B:n"> hole into the shell, put the completed markup in a hidden <div id="S:n"> later in the stream, and used its $RC script to move it into place. The browser painted the page first with nothing where the hero belonged, then inserted 38 KB of hero. With the footer already on screen, that is a shift of nearly the whole viewport, which is how one page reaches a CLS of 0.999.
The same thing happened with the skeletons. The list hero had a ListHeroSkeleton sized for the heading and two lines of lead text. It still produced a desktop CLS of 0.294 on the recipe, blog and event listings, because the swap happened late enough that the footer had already been painted under the skeleton.
Two details make this easy to miss:
The boundary was large and the content was ready. The segments that moved were the big ones: the 38 KB product hero, a 58 KB nutrients grid, the full product grid on three promotional listings. Small finished blocks stayed inline in the shell.
The reveal waits. Since React 19.2, the server renderer batches the reveal of streamed Suspense boundaries "for a short time" so that server and client reveals behave the same, and stops batching when the page load approaches 2.5 seconds. On the nutrients hub the grid appeared about 300 ms after first paint, into an empty fallback, and pushed the cross-index callout and the footer out of the viewport (CLS 0.24 in English, 0.33 in French).
Headless test runs on a fast machine did not show any of this reliably. Lab tools did, once I looked at the shift sources instead of the score.
The fix: error boundaries for static blocks, Suspense only where something waits
The change itself is small. BlockBoundary was split so blocks can take only its error half:
The rule I now apply to every block in the page builder:
The third row needed two more changes. The blog and event listings have a client-side filter island that reads the URL, so it really does suspend during the prerender. The hero above it is now in the shell, and the grid container reserves its room so the footer starts below the fold until the island arrives:
On the store finder, a small component that only reads ?sku and ?lat/?lng from the URL sat in an empty Suspense at the top of <main>. It renders nothing, but its unfilled <template id="B:n"> sat ahead of the page heading. Moving that Suspense below the finder took the hole out of the first viewport.
The last case was the simplest. Three promotional product listings wrapped their grid in <Suspense fallback={null}> although the grid on those pages reads no URL state at all. The default product listing had already dropped that boundary and shipped 24 cards in its shell with a CLS of 0.001. The promotional variant had been copied before that change and never got it. Removing the boundary took featured, new and best sellers from 0.38 to 0.51 down to 0.001.
Results
Across 10 page types, desktop and mobile, three samples each, throttled and unthrottled, the Playwright CLS probe measured 0 in 119 of 120 samples after the first round of fixes (the last sample failed to load). The above-the-fold hole check below went from 11 failing page types out of 65 to 2. The last two, the store finder and the resources hub, were fixed the next day.
A regression guard that reads the shell, not the score
Lighthouse tells you that something moved. It does not stop the next block from reintroducing the problem. The guard I added is a short script that fetches each page's HTML from the origin, cuts it at the first hidden segment (<div hidden id="S:), and fails the URL when the first-viewport region of <main> in that shell contains an outlined hole or skeleton markup:
python
re, sys, urllib.request
SKEL = re.(, re.I)
() -> []:
cut = html.find()
shell = html cut < html[:cut]
m = re.search(, shell)
m:
[]
main = shell[m.start():]
end = (x x (main.find(), main.find(), cap) x > )
region = main[:end]
holes = re.findall(, region)
[ n holes] + [ s SKEL.findall(region)[:]]
failed =
url sys.argv[:]:
problems = check(urllib.request.urlopen(url).read().decode(, ))
( problems , url, *problems)
failed += (problems)
sys.exit( failed )
The full version also ignores holes whose segment renders nothing visible (only JSON-LD or meta tags), prints the nearest class or id and the segment size, and fetches through the origin with the staging host header, so the CDN cannot hide a stale page. It runs against a list of one URL per page type before and after each release candidate. The heuristic is deliberately crude: "up to the first <h1> or 12 KB" is not the real fold. It caught every case in this article, and it runs in a second without a browser.
Measurement traps that cost time
These are worth knowing before you trust a single score.
What still needed other work
Not every number moved with Suspense. Mobile LCP on the product page stayed around 3 seconds, mostly render delay, caused by a 434 KB render-blocking stylesheet shared by every page and about 400 ms of scripting in one shared chunk. Splitting template CSS per route and slimming listing data in the RSC payload were separate changes with their own measurements, in the spirit of reducing bundle size on a Payload site. Fonts are the other classic shift source, covered in the Next.js 16 Google Fonts guide. None of those would have fixed a 0.999 that came from a wrapper.
What this means if you are paying for a rebuild
For a decision-maker the lesson is short. A page builder with reusable blocks will copy one structural choice into every page. Here, one safety wrapper with good intentions caused measurable layout shift across a fully prebuilt site. The fix took a few lines per block. Ask for two things before launch: lab and probe results per page type against the deployed build, and a guard that fails when a regression comes back. A single PageSpeed screenshot of the home page proves neither.
FAQ
Does this mean I should remove Suspense from my pages?
No. Keep Suspense where something waits for request-time data or a client-only hook. Remove it from blocks that render from data you already have, and keep the error boundary.
Is a skeleton enough if it has the right size?
Not for a finished block that React moves out of the shell. The list hero had a sized skeleton and still shifted the footer. If nothing suspends, there should be no fallback to swap.
How do I see whether my page is affected?
Fetch the raw HTML of a prerendered page and search the part before the first <div hidden id="S: for <template id="B:. A hole above your <h1> with a large S: segment later in the response is the pattern from this article.
Does Partial Prerendering change this?
The holes here appeared in fully prebuilt pages, with no request-time work at all. Partial Prerendering adds request-time holes on top. The same check applies to both.
is a client island that bails out of the prerender (useSearchParams)
Suspense placed after the visible content, plus reserved height for what it will render
Page type
CLS before
CLS after
Notes
Product page, desktop
0.999 (every PSI, Lighthouse and almost every Playwright run)
0
PSI performance 74 → 99
Recipe, blog and event listings, desktop
0.294 (17 of 18 Playwright runs)
0
list hero out of Suspense, grid room reserved
Nutrients hub, English and French
0.24 and 0.33
Re-probed (Playwright)
grid out of Suspense
Promotional product listings (3)
0.38 to 0.51
0.001
local Lighthouse desktop 71–81 → 79–96
# File: scripts/above-fold-holes.py (simplified)
import
compile
r'class="[^"]*skeleton[^"]*"|aria-busy="true"'
def
check
html: str, cap: int = 12_000
list
str
'<div hidden id="S:'
if
0
else
r'<main\b[^>]*>'
if
not
return
'no <main> in shell'
# "Above the fold" = from <main> to the first <h1>, capped at 12 KB of markup
min
for
in
'<h1'
'</main>'
if
0
r'<template id="B:(\d+)"'
return
f'hole B:{n}'
for
in
f'skeleton {s}'
for
in
3
0
for
in
1
'utf-8'
'replace'
print
'PASS'
if
not
else
'FAIL'
bool
1
if
else
0
PageSpeed Insights and WebGL. The home page has a WebGL hero. PSI reported a mobile Total Blocking Time of 28.7 seconds; almost all of it was rendering work in one chunk with only 88 ms of scripting. Local Lighthouse with software GL measured 848 ms. Google's machines render WebGL in software, so the lab score for that page stays near 60 while the hero animates on load, whatever you do in JavaScript. Loading the hero after window.load and idle helped locally; it did not change PSI much.
A busy machine makes local Lighthouse lie. Other agents' test runs had the box at a load of 53 on 12 cores during one pass. I deleted every run with a Lighthouse benchmarkIndex below 1,400 and re-ran it. TBT and render delay move the most with load.
Median score, consistent phases. "Median of three" was taken as the run with the median performance score, so the LCP phases in the report come from one run and add up.
Probes that only see the top frame. A giveaway page embeds a third-party marketing page in an iframe. PSI reported a shift of 0.629 there; the Playwright probe saw 0, because it observes only the top frame. The cause was about 16 MB of unsized images inside the embed, which no change in our code can fix.
Check the build you measured. Each report records the deployed commit next to the results, read from the staging response. One rerun measured a build three commits behind main, on purpose, and said so. Performance evidence from an older build is as misleading as any other launch check run against the wrong deploy, so it belongs in the same pre-cutover routine as the checks in the CMS migration checklist.