Static page with use cache still shows a Suspense fallback on Vercel

[pauksztello]

Summary

I have two static pages, both deployed to Vercel. Both load the same books from a function marked with "use cache" and cacheLife("max"). Neither page reads cookies, headers, or search params. Both are prerendered.

async function fetchLatestBooks() {
  "use cache"
  cacheLife("max")

  return db.books.findLatest()
}

async function LatestBooks() {
  const books = await fetchLatestBooks()

  return (
    <ul>
      {books.map((book) => (
        <li key={book.id}>{book.title}</li>
      ))}
    </ul>
  )
}

// app/with-suspense/page.tsx
export default function Page() {
  return (
    <main>
      <h1>With Suspense</h1>
      <Suspense fallback={<p>Loading books...</p>}>
        <LatestBooks />
      </Suspense>
    </main>
  )
}

// app/without-suspense/page.tsx
export default function Page() {
  return (
    <main>
      <h1>Without Suspense</h1>
      <LatestBooks />
    </main>
  )
}

On Vercel, a refresh of /with-suspense sometimes shows "Loading books...", then the books. A refresh of /without-suspense shows the books immediately, with no flash.

Why does the Suspense fallback show on a static page when the data is already cached? Should cached content on a static page be rendered without <Suspense>?

I am struggling to understand the difference and proper usage.

Additional information

No response

Example

No response

[HIRATRA]

I think the important distinction here is between the cached data and the rendering boundary created by <Suspense>.

"use cache" makes fetchLatestBooks() cacheable and, since it doesn't depend on request-time APIs, it can participate in prerendering/static-shell generation. cacheLife("max") also tells Next.js to keep that cached result available rather than treating it as short-lived dynamic work.

However, <Suspense> is still a rendering boundary. It doesn't mean “only show the fallback when the cache is empty”. It tells React/Next.js that the subtree is allowed to suspend and that the fallback is the UI for that boundary while the subtree isn't ready for the current render/stream.

So I wouldn't interpret the behavior as:

cache hit → Suspense should never render

I'd interpret it more as:

cached data can make the subtree prerenderable, but the Suspense boundary can still affect how that subtree is delivered/rendered.

In your example, the fact that /without-suspense never flashes while /with-suspense sometimes does is actually a useful signal: the database result itself is probably not the thing causing the visible delay. The difference is introduced by the Suspense boundary and how the prerendered/streamed RSC/HTML is consumed on that navigation.

If the books are genuinely part of the static shell and you don't need a loading state for them, I would simply remove the <Suspense> boundary:

export default function Page() {
  return (
    <main>
      <h1>Books</h1>
      <LatestBooks />
    </main>
  )
}

That matches the Cache Components model: use use cache for content you want included in the prerendered output, and use <Suspense> when you intentionally want a subtree to be deferred/streamed or need a fallback UI.

One thing I'd also verify in a minimal reproduction is whether you're testing with a hard refresh versus client-side navigation. Those exercise different cache/rendering paths, so reproducing the flash consistently in both cases would help determine whether this is expected Suspense behavior or an actual Next.js/Vercel rendering issue.

[pauksztello]

I'm talking specifically about hard refreshes. Some questions:

1. Without Suspense: Does the browser wait for the entire page (including data) before displaying anything?
2. With Suspense: Does the browser receive the page first and then the cached data gets streamed separately?
3. Does Suspense actually improve initial page load time in this case, or is there no performance difference?

I am still a bit confused.

[HIRATRA]

Yes — your questions are exactly the right way to look at it. I think my previous answer blurred two different cases, so let me be more precise.

For your specific example, assuming cacheComponents: true, fetchLatestBooks() is actually being prerendered, and you're testing a production build:

1. Without Suspense

If fetchLatestBooks() is inside a "use cache" scope with cacheLife("max"), Next.js can resolve that cached work during prerendering and include the resulting UI in the static shell.

So on a hard refresh, the browser should not need to wait for a separate request to your database before displaying the books. The HTML shell already contains the prerendered result.

In other words:

prerender → cached DB result → HTML shell → browser

This is different from an ordinary uncached async database query, which would block rendering until the query completes. Next.js explicitly recommends use cache when you want data to participate in prerendering.

2. With Suspense

If the component is actually deferred behind a Suspense boundary, then the model changes:

prerender → static shell + Suspense fallback → request-time work → streamed result

The fallback becomes part of the static shell, while the deferred content can be streamed when it becomes available. That's the main purpose of Suspense in this architecture.

So yes, conceptually your second interpretation is correct — but only if that subtree is actually being deferred rather than already being resolved as part of the cached/prerendered output.

3. Does Suspense improve the initial load here?

For this particular example, probably not.

If fetchLatestBooks() is already cached and included in the static shell, adding Suspense doesn't make the database query faster. The data is already available during prerendering.

Instead, Suspense can actually make the UX look worse if it causes the user to see:

Loading books...

before receiving content that could have been included directly in the initial HTML.

Suspense becomes a performance win when the work is genuinely request-time/slow and you want the rest of the page to become visible without waiting for that work. Next.js specifically describes this as allowing independent dynamic sections to render in parallel rather than blocking each other.

There's one important thing I'd check in your reproduction, though:

Are you testing with next dev, or with a production build (next build && next start)?

This matters a lot here. Next.js intentionally bypasses certain caches in development, and a hard refresh is one of the cases documented as potentially disabling the cache.

So I'd test the exact same two pages in production mode and compare:

• next build && next start
• hard refresh
• View Source / initial HTML
• Network → the initial document response
• whether Loading books... is already present in the initial HTML

If the production hard refresh still sends the Suspense fallback first even though the use cache result is definitely part of the prerendered output, then I think you've got a much more interesting Next.js behavior/bug to investigate, rather than simply normal Suspense streaming.

That distinction would also explain why the two versions behave differently without assuming that Suspense itself is making the cached database query slower.

[halilertekin]

I tried a minimal production reproduction of your two routes on Next.js 16.2.10 / React 19.2.1, with cacheComponents: true and a cached async function using cacheLife('max'). I replaced the database call with a 200 ms delay returning one book. Both routes were built as static pages, and the generated HTML contained the book in both cases. The Suspense version had a completed boundary, not the fallback:

<main><h1>With Suspense</h1><!--$--><ul><li>BUILD_TIME_BOOK_SENTINEL</li></ul><!--/$--></main>

I also checked three document requests per route through next start: each contained the book HTML and no <p>Loading books...</p> element. This was local with next build --webpack, not a reproduction of your Vercel deployment.

So I would not conclude that wrapping already-prerendered content in Suspense necessarily makes it stream separately on every hard refresh.

For your three follow-up questions:

1. Without Suspense: if the books are in the prerendered output, the document already contains them. There is no request-time database wait for that static response. This does not mean the browser must wait for every byte of the entire page before painting.
2. With Suspense: the boundary permits a fallback when its content is unresolved, but it does not require a separate request-time render. In the reproduction, the content was resolved during prerendering.
3. Performance: for already-prerendered books, adding a boundary does not make the query faster. Its useful benefit is letting surrounding content render while genuinely deferred work completes.

To distinguish a rendering issue from cache/revalidation behavior, I would compare:

• The installed Next.js version and next.config against the local reproduction.
• The built route HTML and the actual Vercel document response, including the rendered <main> (the fallback text can also appear in serialized scripts without being displayed).
• Whether the fallback is already present in the response or appears only after client code runs.
• Whether surrounding layouts/components access request-time data, whether content was invalidated, and whether server logs show a rendering error. React can emit a Suspense fallback when recovering from a server-render error, too.

A cached function's runtime cache and the prerendered route output are different things; serverless runtime cache persistence alone does not prove the route should display a fallback. See Next.js caching/prerendering, use cache runtime considerations, and React's server-render error recovery.

Could you share the exact Next.js version and a minimal reproduction/deployment? Your snippet alone did not produce the flash in the setup above, so removing Suspense may hide the symptom without explaining the deployment difference.

[icyJoseph]

Try with more content, say 12800 bytes https://github.com/react/react/blob/14c2be8dac2d5482fda8a0906a31d239df8551fc/packages/react-server/src/ReactFizzServer.js#L210-L225 — there's nuance to it, in case you throw an agent at it, it'll point it out, but the content threshold is enough for a test case.

[dfbustosus]

Building on the two replies above — the key thing to check is whether the fallback is baked into the prerendered shell that is actually being served, because that is what determines whether you see a flash.

With cacheComponents (PPR), every <Suspense> boundary is a potential seam between the static shell and dynamic content:

• If the cached function resolves while the boundary is completed during prerender, the rendered content ends up in the prerendered HTML and refreshes should never show the fallback.
• If the boundary does not complete during prerender (e.g. db.books.findLatest() was slow or not yet warm at build time), React aborts it, the fallback is what gets baked into the static shell, and the real content is streamed/resumed at request time. cacheLife("max") then caches the data very aggressively — but the shell with the fallback is already prerendered, so you keep seeing "Loading books..." on every cold refresh of that shell.

That "sometimes" you observed usually means one build had the boundary complete and another didn't (or a revalidation/ISR pass regenerated the shell with a slow DB query).

You can verify which case you're in without guessing:

# Is the fallback in the HTML Vercel is actually serving?
curl -s https://your-app/with-suspense | grep -o "Loading books..."

# Is the fallback in the prerendered artifact from your build?
grep -o "Loading books..." .next/server/app/with-suspense.html

If "Loading books..." appears in the served HTML (not just briefly during hydration), the problem is in the prerendered shell, not the client or the data cache. Fixes then are on the build side: make the cached query fast/deterministic at build time, or drop the <Suspense> boundary for this content (like your /without-suspense page) so the whole route waits and is emitted fully static. Keeping <Suspense> only pays off for content you want to defer to request time.

[icyJoseph]

Hi, this is likely being caused by outlining. HTML still has to be downloaded. If you refer to https://react.dev/reference/react/Suspense#what-activates-a-suspense-boundary, you'll see that:

Waiting for a large boundary’s HTML to arrive during streaming server rendering. Sending HTML takes time, so a boundary with enough content activates even when nothing in it suspends. React reveals the content as the HTML arrives.

Even if your server/CDN has a fully rendered page, when it is requested, the page does not necessarily travel as a whole unit, in one packet to your browser so to speak. It arrives in chunks, and browsers can begin painting the page as those arrive. With outlining, React places the fallback where the boundary is, and sends the boundary's content later in the same HTML document, in a hidden element. The browser paints that fallback UI, and when the content arrives, a small inline script swaps the fallback with the content.

🤖📣: Outlining is decided when the HTML is rendered, mostly based on size: a completed boundary with more than ~500 bytes of content gets outlined once the HTML sent so far, plus the boundary, goes past ~12.8 KB (React source). Your page is prerendered, so the HTML is the same on every request. What varies is whether the browser happens to paint before the swap runs, which is why you only see it sometimes.

You can confirm if outlining is happening by looking at the HTML of the page, like the view-source bit. You'd see something like <!--$?--><template id="B:0"></template><p>Loading books...</p><!--/$-->, and further down <div hidden id="S:0">...your books...</div> followed by a $RC("B:0","S:0") script. Searching for the fallback text alone won't tell you much, because it is always present in the RSC payload inlined in the page.

To your questions:

1. Without Suspense, the browser does not wait for the entire page. It paints progressively as the HTML arrives. The books are part of the HTML in document order, and there's no boundary, so there's no fallback to show.
2. With Suspense, nothing is fetched or streamed separately. It is the same single prerendered document, and the books are already in it. If the boundary is outlined, the books come later in that document and get swapped in. If not, they are inline, just like without Suspense.
3. Performance, for content that is already prerendered, Suspense doesn't make anything faster. It gives React permission to show the fallback. If the books are your main content, keep them outside the boundary, see https://nextjs.org/docs/app/guides/streaming#lcp-largest-contentful-paint. Suspense pays off when the content inside it actually has to wait for request-time work.

Note that, as far as React is concerned, if you wrap content in Suspense, then it is OK to show the fallback. Be it by outlining, slow network, CPU bound conditions etc. This is not Cache Components related necessarily, it is Suspense that gives you this capability.

[pauksztello]

Thanks a lot @icyJoseph.

A follow-up: how should I decide whether to wrap something in or not? Is this the right rule of thumb?

1. Content that’s prerendered or cached with use cache: no Suspense. It goes into the HTML in document order, especially if it’s main or LCP content.
2. Content that needs request-time data (cookies, headers, searchParams, uncached fetches): Suspense, because it has to wait anyway and the rest of the page shouldn’t be held back.

Or are there cases where Suspense still makes sense around cached content? For example, a long list below the fold, or a cacheLife short enough that it isn’t included in the prerender?

[icyJoseph]

With Cache Components, you don't have to decide on item 2 yourself. If request-time data (cookies, headers, searchParams, uncached fetches, connection()) is accessed outside of <Suspense>, Next.js flags it in dev and at build, and links to an explanation, for example https://nextjs.org/docs/messages/blocking-prerender-dynamic. So the framework tells you where a boundary is an option to keep your navigations instant.

That also covers your short cacheLife case too. A cache with revalidate: 0 or an expire under five minutes is not included in the prerender, so it behaves like request-time data and Next.js asks for a boundary. You can either extend the lifetime, or wrap it in Suspense: https://nextjs.org/docs/messages/blocking-prerender-runtime#extend-the-cache-lifetime

The same goes for cached content that can still be cold at request time, for example a [id] route without generateStaticParams. The first request for an id has nothing in the cache yet. With a boundary, the fallback goes out immediately and the content streams in once the cache fills. With Cache Components, Next.js flags this too, because params is request-time data there, and points you to a boundary.

On a fully static page like yours, a cold cache does not stream for visitors in production, even with a boundary. When the page is regenerated, Next.js fills the cache entries first and then writes the HTML, so both a hard refresh and a client navigation get the complete content. After revalidate, or with revalidateTag(tag, "max"), visitors get the previous page while that happens in the background. Once expire passes, the next request waits for the rebuild instead, and still gets the complete page rather than the fallback. So in production, the boundary on this page only shows its fallback through outlining. In next dev it's different: pages render on every request and a hard refresh skips the cache, so you will see the fallback there while a cache fills.

Everywhere else, Suspense is an option, a design choice. A boundary means "it is OK to show the fallback here". So for cached content, the question is whether you want that:

• Main or LCP content: no boundary, so it paints in document order as the HTML arrives.
• A long list below the fold: a boundary is reasonable. That is the outlining from above working in your favor. Content above it can paint without waiting for the list's HTML to download, and React reveals the list when it arrives.

Always refer to https://react.dev/reference/react/Suspense#what-activates-a-suspense-boundary

I've been quite busy today, so I drafted this with a bot, it is mostly my writing but I asked it to further on areas where doubts could arise, hence the long 3rd and 4th paragraphs.

Just for completeness sake, IIRC this still applies: reactjs/react.dev#4689

[dfbustosus]

@icyJoseph's streaming point is the other half of the picture — and the curl check above distinguishes which of the two you are hitting:

Case A — the fallback is in the raw HTML (curl -s <url> | grep 'Loading books' matches): the boundary was punted at prerender time and the fallback is baked into the shell. No amount of streaming tuning fixes that; make the cached query fast/deterministic at build, or drop the <Suspense> for this content.

Case B — the content is in the raw HTML, and you still see a flash: that is the streaming reveal icyJoseph describes — a boundary with enough content activates during download, so the browser paints the fallback until the boundary's chunk arrives. The fix is structural: make the boundary smaller (move <Suspense> closer to the async component so the shell around it is tiny), or remove it for content that is already static on this route.

For the original repro — both pages prerendered, same cached data, only /with-suspense flashes — Case B is very plausible on a slow connection, while Case A shows up even on fast ones. That makes the raw-HTML check the fastest way to know which fix applies.

[icyJoseph]

What model did you use for this? It doesn't quite make sense (I want to know to refine our docs and evals to help this kind of model).

Case A would match because the fallback is in the RSC payload.

Case B is also not quite what I meant, I guess I need to amend my comment. Outlining is a heuristic triggered by the content size of the boundary — mostly — but it isn't activated or anything, the outlining happens at rendering time, and you see the fallback when the browser does progressive painting of the page.

Also the Next.js docs point that LCP content should not be in a boundary, https://nextjs.org/docs/app/guides/streaming#lcp-largest-contentful-paint

And what original repro are you referring to? Is this an automated answer too? referring to your chat context? 😞

[dfbustosus]

@mshearer0 circling back — did the raw-HTML check (curl the deployed URL and grep for the fallback text) tell you which of the two cases you were in? If the fallback is in the served HTML it is the prerender-side fix, otherwise it is the streaming/boundary-size one. Happy to dig further with your build output if you can share what the check showed.

[icyJoseph]

Why are you tagging someone not on thread? is that in reference to another thread? if this is an automated answer, please keep it to a minimum, answer on comment via reply, no need to open a new comment every time.