Streaming Pitfalls: Layout Shift and Waterfalls

Streaming with React Suspense and Next.js 15 is powerful, but it introduces two categories of problems that silently degrade user experience:

• Layout Shift — the page visually jumps when streamed content arrives and replaces a skeleton or placeholder, causing elements to reposition.
• Data Waterfalls — components fetch data sequentially rather than in parallel, so the total load time is the sum of all fetch durations instead of the maximum.

These problems are distinct but often appear together. A waterfall delays when content arrives, and when it finally does arrive, a poorly designed skeleton causes a layout shift. This lesson teaches you to diagnose both and apply targeted fixes.

A waterfall happens when one async Server Component awaits its data before rendering children that also need to fetch data. Because the parent suspends first, children never start fetching until the parent resolves.

Consider this structure:

• DashboardPage awaits getUser() (200 ms)
• Then renders <RecentOrders userId={user.id} /> which awaits getOrders(userId) (300 ms)
• Then renders <Recommendations userId={user.id} /> which awaits getRecommendations(userId) (400 ms)

Total wait: 200 + 300 + 400 = 900 ms. With parallel fetches it could be max(200, 300, 400) = 400 ms. The cascade is the waterfall.

The telltale sign of a waterfall is sequential await calls where results are not interdependent, or passing fetched data as props into children that then fetch more data themselves.

The example below shows a page-level waterfall. Notice how RecentOrders cannot start loading until getUser finishes, even though userId could have been passed from a session or URL param instead.

The primary fix is to initiate all independent fetches at the same time using Promise.all (or separate fetch calls that are not awaited until needed). When you need to pass data down, hoist the parallel fetches to the page level.

Key rules:

• Start every independent fetch before the first await.
• Use Promise.all to wait for all of them together.
• Pass resolved data as props; children no longer need to fetch.

When you wrap independent async components in separate <Suspense> boundaries, Next.js can stream each section as it resolves — without waiting for siblings. This gives users partial content immediately.

The anti-pattern is wrapping everything in a single <Suspense>: the whole section waits for the slowest child. Split boundaries granularly so fast components appear first.

Layout Cumulative Layout Shift (CLS) in streamed pages occurs when the skeleton placeholder has different dimensions than the real content that replaces it. When React swaps the fallback for live content, surrounding elements reposition — a jarring visual jump.

Common causes:

• A skeleton that is shorter or taller than the actual component.
• Images without explicit width and height attributes that cause reflow on load.
• Font loading causing text reflow after content streams in.
• Conditionally rendered elements that change page height after hydration.

The fix is to make your skeletons dimensionally accurate — same height, padding, and grid structure as the real component.

A good skeleton mirrors the real component's layout grid. Use fixed heights, matching gap values, and the same number of placeholder rows as the real list will likely render. Tailwind's animate-pulse utility handles the shimmer effect.

The example below pairs a real OrdersList component with a skeleton that has the same outer height and row structure, preventing layout shift when the real data streams in.

Images are a leading cause of layout shift in streamed content. When an <img> loads after the skeleton is replaced, the browser does not know its dimensions and allocates no space — then suddenly reflows the page.

The fix is always to provide width and height attributes (or CSS aspect-ratio) so the browser reserves the exact space before the image loads. Next.js's built-in Image component enforces this automatically when you provide width and height props.

Before fixing, you need to confirm a waterfall exists. Two tools help:

• React DevTools Profiler — record a page load and look at the Flamegraph. Suspense boundaries that resolve one after another in a staircase pattern signal a waterfall.
• Chrome DevTools Network tab — filter by Fetch/XHR. If requests start only after previous ones finish (a staircase in the waterfall view), you have a waterfall.

In Next.js 15, you can also enable verbose logging by setting logging: { fetches: { fullUrl: true } } in next.config.ts to see every server-side fetch with its timing in the terminal during development.

Sometimes you cannot eliminate a dependency but want to avoid blocking the whole page. React 19's use() hook (available in Next.js 15 App Router) lets you pass a Promise as a prop and suspend only the component that consumes it — not the parent.

This pattern lets the parent render instantly with whatever data it has, then stream in the slower section. It is the typed, idiomatic successor to the old trick of passing promises down as props.

Apply these checks to every page that uses streaming:

• Parallel fetches — verify that independent fetch calls are started before any await and combined with Promise.all.
• Granular Suspense — each independently streamed section has its own <Suspense> boundary; never one giant boundary around the whole page.
• Dimensionally accurate skeletons — skeleton height, padding, and grid match the real component to avoid CLS.
• Images with reserved dimensions — always width/height on next/image; never unspecified dimensions on streamed images.
• Font stability — use next/font to load fonts at build time and avoid FOUT-driven reflow after hydration.
• Defer with use() — for unavoidably slow sections, pass a Promise prop and let the child suspend rather than blocking the parent.

Review the following Next.js 15 Server Component. A performance audit shows that ProductList and ReviewSummary are loading sequentially instead of in parallel, causing a 600 ms waterfall. Which change best fixes this?

export default async function ProductPage({ params }: { params: { id: string } }) {
  const product = await getProduct(params.id); // 200 ms
  const reviews = await getReviews(params.id); // 400 ms
  return (
    <>
      <ProductList product={product} />
      <ReviewSummary reviews={reviews} />
    </>
  );
}

This lesson covered the two most common pitfalls in streamed Next.js 15 pages and how to fix them:

• Data Waterfalls — caused by sequential await calls for independent data. Fix with Promise.all to parallelise fetches, and with granular <Suspense> boundaries so each section streams in as soon as its own data is ready.
• Layout Shift — caused by skeleton placeholders that do not match the dimensions of real content. Fix by matching skeleton height and structure to the real component, using next/image with explicit dimensions for all streamed images, and using next/font to prevent font-driven reflow.
• Deferring slow sections — React 19's use() hook lets you pass a Promise as a prop so only the consuming child suspends, keeping the rest of the page unblocked.

Always diagnose with the Network waterfall tab and Next.js fetch logging before optimising, so you fix real bottlenecks rather than guessing.