A loading skeleton on a page whose content you already know is a symptom, not a design problem. This is how I stopped polishing skeletons on a Next.js 16 + Payload site, prebuilt all 2,045 public pages from Payload at build time, and then had to remove the Suspense boundaries that kept painting a skeleton on top of fully static HTML.
If your Next.js pages come from a CMS, you know every URL before the first visitor arrives. With Payload you can list every published slug in generateStaticParams, build every page ahead of time, and let cache tags handle edits made after the build. Once you do that, page-level skeletons have nothing left to wait for. The catch is that React will still paint a skeleton first on a fully prebuilt page if a large finished section sits inside a Suspense boundary, and loading.tsx counts as one. So the fix comes in two parts: prebuild everything, then remove the boundaries around content that is already there.
Tested on 13 November 2026 with Next.js 16.4.6 (cacheComponents and partialPrefetching on), React 19.2.7, Payload 3.93 on Postgres, and a production build of a multi-site catalogue: products with a URL per variant, recipes, blog posts, events and composable pages, in English and French.
The skeleton that started it
I was testing a product page that nobody had visited yet, with the browser throttled to 3G. The right product skeleton appeared first. Then the navbar vanished, and a much more generic skeleton took over: a title bar, a subtitle bar and a two-column grid. Then the real page arrived and everything moved. Two skeletons were competing, and neither one matched the page.
The diagnosis was straightforward once I read the route tree. Three loading states were stacked on the product route. The product folder's own loading.tsx showed the correct skeleton. The shared page renderer had its own Suspense boundary with a generic fallback, and that was the "basic" skeleton taking over. A loading.tsx one level up, on the product list, also wrapped the detail route. The navbar disappeared because it was rendered inside the cached page, not in the layout, so it arrived with the page and not before it.
My first instinct was to make the skeletons better. Give every component a skeleton twin, a carbon copy in terms of layout. Compose page skeletons only from those twins, give every composable Payload block a { Component, Skeleton } pair, and wrap each section in its own Suspense so the twins could show independently. Claude worked out the design with me, including a typed block table that refuses a block without a skeleton. It also listed the costs honestly. One cached page would become several cache entries. Every twin would have to match its real height, or I'd swap the cascade for layout shift. And because the block data was resolved for the whole page at once, the blocks would arrive together anyway, so the twins would rarely show.
The question that changed the plan
Halfway through that design I asked something I thought was a side question: why does a statically generated page need a skeleton at all? I had assumed streaming skeletons were only for dynamic pages.
The answer was that these pages weren't static. Claude laid out when a skeleton is actually visible:
Visit
Every product page's generateStaticParams returned only a placeholder site used to validate the build. Real pages rendered on their first visit and were stored afterwards. So the skeleton mattered most in exactly the case I had been testing, a cold cache, and the best skeleton in the world would only make a slow first render look a little better.
That was the moment the work flipped. We know every URL ahead of time, because they all live in Payload. We could fetch every slug at build time and generate the pages before anyone asks for them. I was solving the wrong issue.
Why the pages weren't prebuilt already
There was a reason, and it's worth naming because it's a common one. The project had a documented rule that builds stay database-free: one Docker image was built once and promoted from staging to production, so no content could be baked in at build time. A unit test even failed the build if any route's generateStaticParams returned a real site. Claude's first suggestion respected that rule and proposed warming the cache instead, by requesting every sitemap URL after each deploy.
Warming would have hidden the problem, not removed it. I reversed the rule. Each environment builds its own image against its own database. CI, which has no database and no credentials, keeps building the placeholder site, so type checks and route validation still run there. A single build flag, PRERENDER_CONTENT=1, decides which of the two you get.
Step 1: one shared params module, reusing the sitemap
The project has close to a hundred page.tsx files under the tenant segment. Writing a Payload query in each one would have been a maintenance trap, and every query would have been a chance to list URLs the proxy doesn't actually serve. The better source already existed: the sitemap code enumerated every published URL per site and per language from Payload.
So the params live in one module that every page calls. It reuses the sitemap's enumeration, drops the sitemap's noindex filter (a noindex page is still a page), adds the variant URLs and each site's home page, and runs every path through the same normaliser the proxy uses to rewrite requests. That last part is what makes French URLs land in the right folders, and it skips any URL that would redirect.
The module exports three functions: one for folders with no slug of their own, one for folders with a single [slug], and one for the catch-all, which gets every published URL that no other folder owns. The catch-all is what covers composable pages, the home page and the taxonomy pages. The app folders are read from disk, so a new route folder is picked up without editing a list.
Without the flag, every route gets only the placeholder site, so CI validates each route without rendering real content. With the flag, the same call returns every real URL for that folder.
Step 2: make the build survive talking to the database
The first proof was the recipes folder alone: 195 pages in 3.3 minutes, and the build output showed no postponed state, so the pages were fully static. The first full build, all routes at once, failed with Postgres error 53300, too many connections. next build runs one Payload instance per worker, the build used 11 workers, and Payload's Postgres pool defaults to 10 connections each. The fix is to cap the pool only during the production build:
The second adjustment was the per-page time limit. In the recipes proof, the first renders of each worker took longer than Next's default 60 seconds and only succeeded on retry. The likely cause is Payload starting cold in every worker, but I haven't confirmed that. Content builds now get a longer limit and a fixed worker count of six. With three connections per worker, six workers stay well inside Postgres' limit even while the running app uses the same database:
With both changes, the full build produced 2,045 pages in 5 minutes 40 seconds, 4.3 minutes of which was page generation. The full build had no timeouts at the 300-second limit. I didn't test whether a smaller limit would also have worked.
Step 3: ISR for anything published after the build
Prebuilding raises the obvious question: what happens to a recipe an editor publishes an hour after the deploy? This is ISR's job, but with cacheComponents on it doesn't look like the ISR you may know. Route segment config such as export const revalidate and dynamicParams is removed when Cache Components is enabled, so the pasted examples from the older guide don't apply.
The Cache Components version works on two levels. For a URL that wasn't in generateStaticParams, Next.js serves the App Shell straight away, renders the page in the background with the now-known params, and serves the finished page to every later visitor. For a page that was prebuilt and then edited, the existing "use cache" tags expire the stored page and it regenerates. So an editor never has to wait for a rebuild, and a visitor never gets a page rendered per request. The bundled Next.js guide on ISR with Cache Components covers the unlisted-URL behaviour in detail. My older ISR explainer is useful background, but it describes the previous model.
Step 4: move search parameters into the browser
A page that reads searchParams on the server can't be one prebuilt file per URL, so the pages that filter, paginate or preselect from the query string had to change. The rule we settled on: the page stays prebuilt, and the part that depends on ?goal=, ?page=, ?sku= or ?ids= becomes a client island that reads the URL in the browser. The product and recipe listings, the store finder and the product comparison all work this way now. Variant selection never needed it, because every variant already had its own URL.
The first version of the paginated listings rendered every page and page size into the HTML and showed one after hydration. That worked, but it's the heavier version. The cleaner pattern is one slim index per listing: every card's slug, title, filter keys and smallest base64 image preview, with paging and filtering done in the browser and full images loaded only when a card is shown. That's a topic of its own, and if you'd rather keep this logic on the server, my route separation fix for searchParams is the alternative.
Two things surfaced here. First, code that reads the clock goes stale on a prebuilt page. The giveaway page picked the current giveaway by today's date, and the events listing split upcoming from past events with a new Date() at module level, which froze "now" at build time. Rendering per request had been hiding both. The giveaway page now expires at the next midnight, and events expire at the next event boundary and hydrate with the server's date before switching to the visitor's.
Second, the comparison page exposed a "use cache" trap. Its products now came from a Payload endpoint called from the browser, and every shared comparison link failed with cacheLife() can only be called inside a "use cache" or "use cache: private" function. Code reached through the Payload config (endpoints, hooks, jobs) is compiled without the "use cache" transform. The directive is stripped, the function runs as plain code, and cacheLife() throws. The endpoint had been broken for a while, but nobody noticed because the page used to load its products on the server. The fix was to give the loader an uncached path and call that from the endpoint. Endpoint responses weren't cached anyway.
Step 5: remove the Suspense boundaries around finished content
At this point every public page was prebuilt, and I expected the skeletons to be gone. They weren't. A measuring session scanned one URL per page type, 65 URLs in all, and found that none of them painted content first. On 60 of the 65, the first part of the HTML, everything before the first hidden segment, held only the skeleton. On one page that first part was 2,776 bytes: a banner and a <main aria-busy="true"> full of grey bars.
The cause is how React streams a Suspense boundary that has already finished. I checked it in the react-dom 19.2.7 server build. A completed boundary larger than 500 bytes is outlined when the HTML written so far plus that boundary would pass progressiveChunkSize, which defaults to 12,800 bytes. It's also outlined when it contains stylesheets or images React treats as suspending. An outlined boundary is written as its fallback, with the real content in a hidden <div hidden id="S:…">, and a small script swaps them later. A whole page's content is always far past 12,800 bytes, so a page-level boundary is always outlined. Next.js exposes no setting for this threshold.
On these pages the swap script sat behind roughly 300 KB of inline RSC payload that the browser had to parse first. So first paint showed the skeleton, and the content appeared a beat later. First Contentful Paint and Largest Contentful Paint were identical on every page, because a skeleton has no contentful element. On some desktop runs the swap itself caused layout shift.
The fix is to stop wrapping prebuilt content. That meant removing the Suspense in the tenant layout, the one inside the shared page renderer (it stays only on the draft-preview branch), the page-level boundaries in the legacy page shells and every loading.tsx on a prebuilt route. The layout now carries a comment so nobody adds the boundary back:
tsx
// File: src/app/(frontend)/[locale]/[tenant]/layout.tsx (excerpt)
<ThemeBoundary themeKey={site.themeKey}>
{/* No Suspense here: every public page is prebuilt, so its content belongs in
the shell. A boundary around a large finished page makes React outline it
(fallback in the shell, content revealed by script later). */}
{children}
</ThemeBoundary>
The one routed page that keeps a boundary is a signed-in portal that reads the session per request, which is exactly what Suspense is for. After the change, 63 of the 65 page types painted their content first on staging. The two exceptions were a URL that redirects to a different site and a legacy page that's only an iframe.
Why loading.tsx can't stay "just for clicks"
I resisted removing loading.tsx at first, because I thought it only mattered for in-site navigation. That's the mistake worth spelling out. loading.tsx wraps the page in a Suspense boundary in the server-rendered output, so the boundary that shows a skeleton on a click also wraps the HTML of a hard load: a refresh, a typed URL or a visitor arriving from Google. You can't keep it for clicks without paying for it on the loads that PageSpeed and Google's field data measure.
Hard load (Google, refresh)
For clicks, the replacement is prefetching plus a small pending state on the link. The navbar links already prefetch the full page when the visitor hovers, focuses or touches them. For a click that beats the prefetch, useLinkStatus() shows feedback without touching the server HTML. It only works in a descendant of <Link>, so the hint rides inside the link:
The CSS dims .nav-link-pending[aria-busy="true"]. In the real project the link is a wrapper that turns on full prefetching only on intent, which is a separate article. A prefetched click skips the pending state entirely and switches instantly. The project's own session didn't check this component in a browser, so test the drawer case in yours.
So the skeleton twins didn't disappear entirely. They shrank from "every page and every block" to the handful of parts that genuinely load later in the browser: the filtered listings, the saved list, the quiz and the store-finder results. Blocks on composable pages don't need them, because they're prebuilt with the page.
The last boundary: fallback={null} around a big block
The "63 of 65" scan only checked whether the header appeared before any hidden segment. A rerun on staging showed the product page on desktop still had a Cumulative Layout Shift of 0.999 in every PageSpeed run, and the recipe, blog and event listings sat around 0.294.
The culprit was a block-level boundary. The product hero block rendered <Suspense fallback={null}> around its content. A null fallback looks harmless because it doesn't show a skeleton, but the same outlining rule applies. The hero, details and store finder were written as hidden segments, so first paint showed the header, the reviews and the footer. Then the hero was revealed above the reviews and pushed everything down. Desktop was worse than mobile because the reviews and footer fit inside the first desktop viewport. The listings had the same pattern: a tiny <main> that left the footer on screen until the grid was revealed.
The fix was to render above-the-fold blocks directly in the HTML, with no Suspense, and to give the client filter island a reserved height. Afterwards the product page scored 99 on desktop PageSpeed, up from 74, with CLS 0, and the Playwright CLS probe measured 0 in 119 of 120 samples. A guard test now fails if above-the-fold content sits inside an outlined segment.
Conclusion
The skeleton I spent a morning designing was covering for pages that should never have needed one. Every URL on a Payload site is known at build time, so the fix was to list them all in generateStaticParams from one module built on the sitemap's queries. That meant building each environment against its own database, capping the Postgres pool during the build, leaving later edits and new URLs to ISR under Cache Components, and moving search-parameter logic into client islands. Then came the part nobody warned me about: on prebuilt pages, any Suspense boundary or loading.tsx around finished content still paints its fallback first, because React outlines large completed boundaries, so those boundaries have to go too, including the fallback={null} ones.