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.