Streaming and partial rendering in NextJS - Deep Dive

Overview - Streaming and partial rendering

What is it?

Streaming and partial rendering in Next.js means sending parts of a web page to the browser as soon as they are ready, instead of waiting for the whole page to finish loading. This lets users see and interact with content faster. It breaks the page into smaller pieces that load independently and appear progressively.

Why it matters

Without streaming and partial rendering, users wait longer to see any content because the browser must receive the entire page before showing anything. This can feel slow and frustrating, especially on slow networks or complex pages. Streaming improves user experience by showing content early and keeps users engaged while the rest loads.

Where it fits

Before learning streaming, you should understand basic React components and Next.js server-side rendering. After mastering streaming, you can explore advanced performance optimizations like server actions and React Server Components for even smoother user experiences.

Mental Model

Core Idea

Streaming and partial rendering send pieces of a page to the browser as soon as they are ready, letting users see content progressively instead of waiting for everything.

Think of it like...

It's like eating a meal where the appetizer arrives first, so you start enjoying food while the main course is still being prepared, instead of waiting for the whole meal at once.

┌───────────────┐
│ Server starts  │
│ rendering page│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Send header   │
│ and navbar    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Send main     │
│ content chunk │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Send footer   │
│ and scripts   │
└───────────────┘

Browser renders each chunk as it arrives, showing page progressively.

Build-Up - 7 Steps

1

Foundation

What is server-side rendering

Concept: Introduce how Next.js renders pages on the server before sending to the browser.

Next.js can generate the full HTML of a page on the server. When a user requests a page, the server builds the entire page and sends it all at once to the browser. The browser then shows the complete page.

Result

Users see the full page only after the server finishes building it and sends it all.

Understanding server-side rendering is key because streaming builds on sending HTML from the server, but in smaller parts.

2

Foundation

How React components render on server

Concept: Explain that React components can be rendered to HTML strings on the server.

React components are functions that return UI elements. On the server, Next.js runs these functions and converts the result into HTML text. This HTML is what the browser uses to display the page.

Result

React components become HTML strings that the server sends to the browser.

Knowing that React components turn into HTML on the server helps understand how streaming can send parts of this HTML progressively.

3

Intermediate

What is streaming rendering

🤔Before reading on: do you think streaming sends the whole page at once or in parts? Commit to your answer.

Concept: Streaming rendering means sending HTML chunks to the browser as soon as they are ready, not waiting for the whole page.

Instead of waiting for the entire React tree to render, Next.js can send the first parts of the page immediately. As more components finish rendering, their HTML is sent too. The browser can start showing content early and update as more arrives.

Result

Users see the page load progressively, improving perceived speed.

Understanding streaming changes how you think about page loading: it's about early delivery, not waiting for completeness.

4

Intermediate

Partial rendering with React Server Components

🤔Before reading on: do you think React Server Components run on client or server? Commit to your answer.

Concept: React Server Components run on the server and can stream their output to the client, enabling partial rendering.

React Server Components let you split UI into server-only parts. These parts render on the server and stream HTML to the client. The client combines these streamed parts with client components for interactivity.

Result

The page is built from streamed server parts plus interactive client parts, improving performance.

Knowing how server and client components work together explains how partial rendering is possible and efficient.

5

Intermediate

Using Suspense to coordinate streaming

🤔Before reading on: does Suspense delay rendering or allow partial rendering? Commit to your answer.

Concept: React Suspense lets you show fallback content while waiting for parts to load, coordinating streaming chunks.

When a component is not ready, Suspense shows a placeholder. Once the component finishes rendering on the server, its HTML streams to the client and replaces the placeholder. This creates smooth partial rendering.

Result

Users see placeholders replaced by real content progressively.

Understanding Suspense is crucial because it controls how partial content appears and updates during streaming.

6

Advanced

Next.js streaming API and usage

🤔Before reading on: do you think streaming requires special Next.js APIs or happens automatically? Commit to your answer.

Concept: Next.js provides APIs and conventions to enable streaming and partial rendering in your app.

In Next.js App Router, server components stream HTML by default. You can use async components and Suspense boundaries to control streaming. The framework handles sending chunks to the browser progressively without extra setup.

Result

Your app streams content automatically, improving load times without complex code.

Knowing Next.js streaming APIs lets you design components that stream efficiently and handle loading states gracefully.

7

Expert

Streaming internals and edge cases

🤔Before reading on: do you think streaming always improves speed or can sometimes cause issues? Commit to your answer.

Concept: Streaming uses HTTP chunked transfer and React's rendering pipeline, but can have pitfalls like layout shifts or caching challenges.

Streaming sends HTML chunks over HTTP as they become ready. React coordinates rendering and hydration on the client. However, if chunks arrive out of order or placeholders cause layout jumps, user experience can suffer. Also, caching streamed pages requires careful handling.

Result

Streaming can greatly improve perceived speed but needs careful design to avoid visual glitches and caching problems.

Understanding streaming internals helps you anticipate and fix subtle bugs and optimize real-world apps.

Under the Hood

Next.js uses React's server rendering to generate HTML on the server. Instead of waiting for the full React tree, it streams HTML chunks as components finish rendering. These chunks are sent over HTTP using chunked transfer encoding. The browser parses and renders these chunks progressively. React on the client hydrates the streamed HTML to add interactivity. Suspense boundaries mark where placeholders appear and get replaced as chunks arrive.

Why designed this way?

Streaming was designed to improve user experience by reducing time to first meaningful paint. Traditional server rendering sends the full page at once, causing delays. Streaming leverages HTTP/1.1 chunked transfer and React's async rendering to send partial content early. Alternatives like client-side rendering delay content until JavaScript loads, which can be slower. Streaming balances server and client work for faster perceived load.

┌───────────────┐
│ React Server  │
│ renders chunk │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ HTTP chunked  │
│ transfer sends│
│ HTML chunk    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Browser parses│
│ and renders   │
│ chunk         │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ React hydrates│
│ streamed HTML │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does streaming mean the entire page is sent instantly? Commit yes or no.

Common Belief: Streaming sends the whole page instantly to the browser.

Reality: Streaming sends the page in parts, progressively as each part is ready, not all at once.

Why it matters: Believing streaming sends everything instantly leads to expecting no loading delays, causing confusion when placeholders appear.

Quick: Do React Server Components run on the client? Commit yes or no.

Common Belief: React Server Components run on the client like normal React components.

Reality: React Server Components run only on the server and stream HTML to the client.

Why it matters: Misunderstanding this causes misuse of server components, leading to runtime errors or performance issues.

Quick: Does Suspense block the entire page from rendering? Commit yes or no.

Common Belief: Suspense stops the whole page from rendering until all data is ready.

Reality: Suspense only blocks the part inside it, allowing other parts to render and stream.

Why it matters: Thinking Suspense blocks everything prevents using it to improve partial rendering and user experience.

Quick: Is streaming always faster than static rendering? Commit yes or no.

Common Belief: Streaming always makes pages load faster than static rendering.

Reality: Streaming improves perceived speed but can cause layout shifts or caching complexity, sometimes making static better for simple pages.

Why it matters: Assuming streaming is always best leads to overcomplicated solutions and unexpected bugs.

Expert Zone

1

Streaming performance depends heavily on network conditions and chunk sizes; too many small chunks can hurt performance.

2

Hydration mismatches can occur if streamed HTML and client components are out of sync, causing runtime errors.

3

Caching streamed pages requires careful invalidation strategies because partial content may vary per user or request.

When NOT to use

Streaming is not ideal for very simple pages where full static rendering is faster and simpler. Also, avoid streaming if your app has complex client-side state that requires full hydration upfront. In those cases, static generation or client-side rendering might be better.

Production Patterns

In production, Next.js apps use streaming with Suspense boundaries to load critical UI first, like navigation and headers, while deferring heavy content. They combine server components for data fetching with client components for interactivity. Monitoring layout shifts and using caching headers carefully ensures smooth user experience.

Connections

HTTP chunked transfer encoding

Streaming in Next.js uses HTTP chunked transfer to send partial HTML.

Understanding HTTP chunked transfer helps grasp how browsers receive and render streamed content progressively.

Progressive image loading

Both streaming and progressive image loading show content in parts to improve perceived speed.

Knowing progressive image loading techniques clarifies why showing partial content early improves user experience.

Assembly line manufacturing

Streaming is like an assembly line where parts are completed and passed on immediately instead of waiting for the whole product.

Seeing streaming as an assembly line helps understand how breaking work into chunks speeds up delivery.

Common Pitfalls

#1 Sending all content at once defeats streaming benefits.

Wrong approach:

export default function Page() {
const data = fetchDataSync();
return {data};
}

Correct approach:

export default async function Page() {
const data = await fetchDataAsync();
return {data};
}

Root cause:

Using synchronous data fetching blocks streaming because the server waits for all data before sending.

#2 Not using Suspense causes blank areas during streaming.

Wrong approach:

export default async function Page() {
const data = await fetchData();
return {data};
}

Correct approach:

import { Suspense } from 'react';

export default function Page() {
return (
}>

);
}

Root cause:

Without Suspense, React cannot show placeholders, so users see empty spaces until content arrives.

#3 Mixing client and server components incorrectly breaks streaming.

Wrong approach:

'use client';

export default async function Page() {
const data = await fetchData();
return {data};
}

Correct approach:

export default async function Page() {
const data = await fetchData();
return ;
}

Root cause:

Marking server components as client disables streaming and causes hydration errors.

Key Takeaways

Streaming and partial rendering let Next.js send page parts early, improving user experience by showing content progressively.

React Server Components and Suspense work together to enable streaming by rendering on the server and managing loading states.

Streaming uses HTTP chunked transfer to send HTML chunks, which the browser renders and hydrates incrementally.

Misusing streaming concepts can cause layout shifts, hydration errors, or negate performance benefits.

Understanding streaming internals and Next.js APIs helps build fast, smooth, and scalable web apps.

Practice

1. What is the main benefit of streaming in Next.js when rendering pages?

easy

A. It caches the whole page on the client side before showing anything.

B. It delays sending the entire page until all data is loaded.

C. It disables server-side rendering completely.

D. It sends parts of the page to the browser as soon as they are ready.

Solution

1. Step 1: Understand streaming concept in Next.js

   Streaming means sending parts of the page to the browser immediately when they are ready, not waiting for the whole page.

2. Step 2: Compare options with streaming behavior

   It sends parts of the page to the browser as soon as they are ready. matches this behavior exactly, while others describe delaying or caching, which are not streaming.

3. Final Answer:

   It sends parts of the page to the browser as soon as they are ready. -> Option D

4. Quick Check:

   Streaming = send parts early [OK]

Hint: Streaming means show parts early, not wait for all [OK]

Common Mistakes:

• Thinking streaming waits for full page
• Confusing streaming with client caching
• Assuming streaming disables server rendering

2. Which of the following is the correct way to use Suspense for partial rendering in Next.js?

easy

A. } />

B. } />

C. }>

D. }>

Solution

1. Step 1: Recall Suspense usage pattern

   Suspense wraps the async component and uses the fallback prop to show a loading state while waiting.

2. Step 2: Match correct syntax

   <Suspense fallback=<Loading />><AsyncComponent /></Suspense> correctly wraps AsyncComponent inside Suspense with fallback. Others misuse fallback or component placement.

3. Final Answer:

   <Suspense fallback=<Loading />><AsyncComponent /></Suspense> -> Option C

4. Quick Check:

   Suspense wraps async with fallback [OK]

Hint: Suspense wraps async component with fallback prop [OK]

Common Mistakes:

• Placing fallback inside async component
• Not wrapping async component with Suspense
• Using fallback incorrectly as a child

3. Given this Next.js server component code using streaming:

export default async function Page() {
  const user = await fetchUser();
  return (
    <>
      
Welcome {user.name}
      Loading posts...
}>
        
      
    </>
  );
}

What will the user see first in the browser?

medium

A. Only 'Loading posts...' until all data loads.

B. The heading with user name, then 'Loading posts...' while posts load.

C. The full page with heading and posts at once.

D. An empty page until fetchUser finishes.

Solution

1. Step 1: Analyze async data fetching and rendering

   The user data is awaited before rendering, so the heading with user name shows immediately.

2. Step 2: Understand Suspense fallback behavior

   The Posts component is wrapped in Suspense with a fallback, so 'Loading posts...' shows while posts load.

3. Final Answer:

   The heading with user name, then 'Loading posts...' while posts load. -> Option B

4. Quick Check:

   Await user shows heading first, Suspense fallback next [OK]

Hint: Awaited data shows first; Suspense fallback shows during async child load [OK]

Common Mistakes:

• Thinking Suspense fallback shows before awaited user data
• Assuming full page waits for all data
• Ignoring Suspense fallback usage

4. Identify the error in this Next.js streaming code snippet:

export default async function Page() {
  return (
    Loading...
}>
      
    
  );
}

function AsyncData() {
  const data = fetchData();
  return <p>{data.message}</p>;
}

medium

A. AsyncData is not marked async and fetchData is not awaited.

B. Suspense cannot wrap components in Next.js.

C. fetchData should be called inside Page, not AsyncData.

D. The fallback prop must be a string, not JSX.

Solution

1. Step 1: Check AsyncData function for async usage

   AsyncData calls fetchData() but does not await it or mark function async, causing a promise to be rendered.

2. Step 2: Confirm Suspense usage and fallback validity

   Suspense usage is correct, and fallback can be JSX, so no error there.

3. Final Answer:

   AsyncData is not marked async and fetchData is not awaited. -> Option A

4. Quick Check:

   Async function must await async calls [OK]

Hint: Async components must await async calls inside [OK]

Common Mistakes:

• Not marking component async when using await
• Rendering unresolved promises
• Misunderstanding Suspense fallback types

5. You want to stream a page showing user info and their posts. User info loads fast, posts load slowly. How do you combine streaming and partial rendering to show user info immediately and posts with a loading fallback?

hard

A. Make Page async, await user data, render user info immediately, wrap Posts in Suspense with fallback.

B. Render user info and posts inside one Suspense with fallback for both.

C. Fetch posts first, then user info, and render all at once without Suspense.

D. Use client-side fetching for posts and server-side for user info without Suspense.

Solution

1. Step 1: Await fast user data in Page component

   Mark Page async and await user data so user info renders immediately.

2. Step 2: Wrap slow posts component in Suspense with fallback

   Wrap Posts in Suspense with a loading fallback to show partial rendering while posts load.

3. Final Answer:

   Make Page async, await user data, render user info immediately, wrap Posts in Suspense with fallback. -> Option A

4. Quick Check:

   Await fast data, Suspense slow data [OK]

Hint: Await fast data, Suspense slow parts with fallback [OK]

Common Mistakes:

• Wrapping all content in one Suspense losing immediate render
• Not awaiting fast data before rendering
• Using client fetching without Suspense for server components