completefrontend
Open lab My progress
THE WEB PERFORMANCE FIELD GUIDE

Streaming HTML

Send a page in pieces: flush the head, stream the HTML in order or out of order with Suspense, and handle status codes once the first byte has left.

By the end, you can
  • 01
    Send a page in piecesFlush the head, stream the body in order, or stream it out of order with a fallback, and measure what each changes.
  • 02
    Read what React and Next.js sendFollow a Suspense boundary from its fallback to the script that swaps in the late content.
  • 03
    Keep status codes and streaming workingDecide the status before the first byte, and find the layers that hold a stream back.

A page that waits for its slowest part

In lesson 35.1, Ravi's server built his Mint tea page for every visit. Now the page has grown. Its 24 reviews come from a separate reviews service, and that service is slow. It takes a whole second to answer.

Ravi's server still waits for everything before it sends a single byte. So Asha stares at a blank screen for over a second. The photo, the name and the price were ready after a quarter of a second. They waited for the reviews.

Does a page really have to wait for its slowest part? No. The server can send the page in pieces, each one as soon as it's ready. That's called streaming. Ravi tried four ways of sending the same page:

  • All at once: wait for the tea and the reviews, then send the whole page. This is lesson 35.1's server rendering.
  • Head first: send the top of the HTML at once. Send the rest when everything is ready.
  • Streamed in order: send each piece as soon as it's ready, from the top of the page to the bottom.
  • Streamed out of order: send a placeholder for the reviews and the rest of the page. Send the reviews when they come.

Asha opened each one. Here are the four, side by side, at three moments:

Ravi's Mint tea page sent four ways, in real frames from Chrome, at 500 ms, 1,250 ms, 1,450 ms after Asha opened it. All at once at 500 ms: a blank page. Head first at 500 ms: a blank page. Streamed in order at 500 ms: the photo, the name and the buy box, with nothing under Reviews. Streamed out of order at 500 ms: the photo, the name and the buy box, with Loading reviews… under Reviews. All at once at 1,250 ms: a blank page. Head first at 1,250 ms: the whole page, reviews and all. Streamed in order at 1,250 ms: the whole page, reviews and all. Streamed out of order at 1,250 ms: the whole page, reviews and all. All at once at 1,450 ms: the words, but no photo yet. Head first at 1,450 ms: the whole page, reviews and all. Streamed in order at 1,450 ms: the whole page, reviews and all. Streamed out of order at 1,450 ms: the whole page, reviews and all.All at onceHead firstIn orderOut of order500 msblankblankblankblankStreamed in order at 500 ms: the photo, the name and the buy box, with nothing under Reviews.no reviews yetStreamed out of order at 500 ms: the photo, the name and the buy box, with Loading reviews… under Reviews.fallback1,250 msblankblankHead first at 1,250 ms: the whole page, reviews and all.whole pageStreamed in order at 1,250 ms: the whole page, reviews and all.whole pageStreamed out of order at 1,250 ms: the whole page, reviews and all.whole page1,450 msAll at once at 1,450 ms: the words, but no photo yet.no photo yetHead first at 1,450 ms: the whole page, reviews and all.whole pageStreamed in order at 1,450 ms: the whole page, reviews and all.whole pageStreamed out of order at 1,450 ms: the whole page, reviews and all.whole page
Real frames from Chrome, from the middle load of each way. Both streamed pages showed the photo and the price at 500 ms.

Look at the first row. At 500 ms, both streamed pages show the photo, the name and the price. The other two show nothing. At 1,250 ms, head first has caught up. All at once is still blank. Here are two moments from each visit:

The first byte, and the photo on screenPop out in the code editor (opens in a new tab)JavaScript
// Asha opens Ravi's Mint tea page, sent four ways. Times in ms after she opened it.// The middle of 5 loads of each way.const ways = [  ["All at once", 1167.9, 1460],  ["Head first", 167.2, 1244],  ["In order", 166.7, 484],  ["Out of order", 166.5, 480],];for (const [way, firstByte, photo] of ways) console.log(`${way}: first byte ${firstByte} ms, photo ${photo} ms`);
  • Lines 1 and 2 are comments. The course loaded each way 5 times, and these are the middle loads.
  • Lines 4 to 7 hold each way: its name, when its first byte arrived, and when the photo was on screen. Times are in milliseconds (ms) after Asha opened the page.
  • Line 9 prints one line per way. The first two are All at once: first byte 1167.9 ms, photo 1460 ms and Head first: first byte 167.2 ms, photo 1244 ms.
  • The last two are In order: first byte 166.7 ms, photo 484 ms and Out of order: first byte 166.5 ms, photo 480 ms.

The photo is the page's largest contentful paint, or LCP, from lesson 17.1. Streaming put it on screen about a second sooner. It was the same server, the same data and the same network. Only the order of sending changed. How can that save a whole second?

Real-life analogyA phone call, not a letter

You have news for a friend. You could write a letter. Your friend reads nothing until you've finished it, sealed it and posted it. Or you could phone. Your friend hears each sentence as you say it. If you stop to look something up, they already know the start.

In real life: Writing the whole letter first
In web performance: Sending the page all at once
In real life: Saying each sentence as you think of it
In web performance: Streaming: sending each piece when it's ready
In real life: Your friend listening as you speak
In web performance: The browser reading HTML as it arrives
In real life: Stopping to look something up
In web performance: The server waiting for the reviews
The main idea

Send each part of the page as soon as it's ready. Then slow data only delays its own part, not the whole page. The browser reads HTML as it arrives. So it can fetch files and paint long before the last byte.

For streaming with React code, see Streaming server rendering. For Next.js, see Streaming with Suspense. For streaming in a large system, see Streaming server-side rendering. Here, you measure it.

How the course recorded it

  • Ravi's page: lesson 35.1's Mint tea page, at £4.80, with 24 reviews. Its stylesheet is now a file of its own, styles.css.
  • Ravi's data: his database gives the tea in 250 ms, as in lesson 35.1. His reviews service gives the reviews in 1,000 ms. Both start when the request arrives.
  • The server: written by hand in Node.js, with no framework, so you can read every line. It gzipped each piece, as in lesson 16.1. The code on this page leaves gzip out. React's own server rendering was recorded too.
  • Asha's network: the course's server played Fast 4G, as in lesson 35.1. Each piece reached Asha 165 ms after the server sent it.
  • Asha's computer: Chrome 157, in a window 500 pixels wide, with the CPU 4 times slower.
  • The loads: each way 5 times, taking turns.

Move through Asha's visits yourself. Each frame is real:

Playground: every way, moment by moment
The Mint tea page, sent eight ways
  1. All at oncea blank page
  2. Head firsta blank page
  3. In orderIn order at 500 ms: the photo, the name and the buy box, with nothing under Reviews.the photo, the name and the buy box, with nothing under Reviews
  4. Out of orderOut of order at 500 ms: the photo, the name and the buy box, with Loading reviews… under Reviews.the photo, the name and the buy box, with Loading reviews… under Reviews
  5. Reacta blank page
  6. Reviews failReviews fail at 500 ms: the photo, the name and the buy box, with Loading reviews… under Reviews.the photo, the name and the buy box, with Loading reviews… under Reviews
  7. Proxya blank page
  8. No flusha blank page
Try it yourself
Asha's screen at 500 ms

Move the slider. Each frame is the last one Chrome had drawn by then, in the middle load of each way.

Chrome 157, a server that plays Fast 4G, a CPU 4 times slower.

Flushing the head early

Start with lesson 35.1's way. Here is the course's server, sending everything at once:

The whole page, when everything is readyJavaScript
// The course's server, sending the whole page at once.async function allAtOnce(response) {  const [tea, reviews] = await Promise.all([getTea(), getReviews()]);  response.writeHead(200, { "content-type": "text/html" });  response.end(head() + top(tea) + reviewList(reviews) + about(tea));}
  • Line 3 asks the database and the reviews service at the same time. Promise.all waits for both. That's 1,000 ms, the slower of the two.
  • Line 4 sends the status, 200, and a header that says the answer is HTML.
  • Line 5 sends the whole page and ends the answer. head(), top(), reviewList() and about() each return one piece of the page's HTML.

Nothing leaves the server until line 3 is done. So the first byte reached Asha at 1,167.9 ms: the 1,000 ms wait, plus the 165 ms trip. That's the page's time to first byte, or TTFB, from lesson 14.1.

But look at the top of the HTML, the head. It needs no data at all:

The head: two files to fetchHTML
<head>  <title>Mint tea, Leaf and Kettle</title>  <link rel="stylesheet" href="styles.css">  <link rel="preload" as="image" href="/nextjs-assets/images-in-nextjs/mint-tea.jpg"></head>
  • Line 3 links the stylesheet.
  • Line 4 is a preload: a line that asks the browser to fetch the photo early, before it reaches the <img>. Lesson 17.3 showed how it helps a photo the browser finds late.
  • The server knows both addresses before it asks the database. Each photo is named after its tea.
Real-life analogyHeating the oven while you mix

You're baking bread. Mixing the dough takes a while. So you switch the oven on first, and it heats up while you mix. You still can't bake until the dough is ready. But when it is, the oven is hot, and the bread goes straight in.

In real life: Switching the oven on first
In web performance: Sending the head first
In real life: The oven heating up
In web performance: The browser fetching styles.css and the photo
In real life: Mixing the dough
In web performance: The server waiting for the tea and the reviews
In real life: No bread until the dough goes in
In web performance: Nothing painted until the body arrives

Sending part of an answer before the rest is ready is called flushing. Lesson 14.2 flushed a shop's head early. Ravi does the same:

The head first, then the restJavaScript
async function headFirst(response) {  response.writeHead(200, { "content-type": "text/html" });  response.write(head());  const [tea, reviews] = await Promise.all([getTea(), getReviews()]);  response.end(top(tea) + reviewList(reviews) + about(tea));}
  • Line 2 sets the status and the header.
  • Line 3 sends the head. This is the flush. In Node.js, the first write() sends the headers and this first piece together.
  • Lines 4 and 5 wait for both, as before, then send the rest.
What the early head changedPop out in the code editor (opens in a new tab)JavaScript
// All at once and head first, in ms after Asha opened the page. The middle of 5 loads each.const allAtOnce = { css: 1349.8, photo: 1448.2, firstPaint: 1404 };const headFirst = { css: 348.1, photo: 449.3, firstPaint: 1244 }; console.log(`Stylesheet arrived ${(allAtOnce.css - headFirst.css).toFixed(1)} ms sooner`);console.log(`Photo arrived ${(allAtOnce.photo - headFirst.photo).toFixed(1)} ms sooner`);console.log(`First paint came ${allAtOnce.firstPaint - headFirst.firstPaint} ms sooner`);
  • Lines 2 and 3 hold three times from each way: when the stylesheet arrived, when the photo arrived, and the first paint.
  • It prints Stylesheet arrived 1001.7 ms sooner and Photo arrived 998.9 ms sooner.
  • Then it prints First paint came 160 ms sooner.

The stylesheet and the photo arrived a second sooner. They were in long before the page needed them. But the first paint came only 160 ms sooner, at 1,244 ms. Why so little? The head holds nothing to see. Asha's screen stayed blank until the body came, and the body still waited for the reviews.

Why it matters: flushing the head gets the files moving. But the page still waits for its slowest data.

Lesson 14.4 did the same job another way, with a 103 Early Hints answer. A 103 sends the links but leaves the final status open. A flushed head has already said 200. The section on status codes shows why that matters.

Streaming the page as it's built

Why stop at the head? The top of the page, with the photo, the name and the buy box, only needs the tea. The tea is ready at 250 ms. So send each piece as soon as its data is ready:

Each piece when its data is readyJavaScript
async function inOrder(response) {  const tea = getTea();  const reviews = getReviews();  response.writeHead(200, { "content-type": "text/html" });  response.write(head());  response.write(top(await tea));  response.end(reviewList(await reviews) + about(await tea));}
  • Lines 2 and 3 start both requests at once, without await. Each one is a promise: a value that will be ready later.
  • Line 5 sends the head straight away.
  • Line 6 waits for the tea, 250 ms, then sends the top of the page.
  • Line 7 waits for the reviews, 1,000 ms, then sends them and the rest, and ends the answer.

This is streaming server rendering. The server sends the HTML in pieces while it's still building the rest. The browser doesn't wait for the end. The HTML standard says the browser must "fill the parser's input byte stream with the fetched bytes" as they arrive. web.dev says streaming lets the browser render HTML in chunks "as it's received". Here is what changed for Asha:

All at once, and in orderPop out in the code editor (opens in a new tab)JavaScript
// All at once and in order, in ms after Asha opened the page. The middle of 5 loads each.const allAtOnce = { photo: 1460, reviews: 1404, lastByte: 1170.5 };const inOrder = { photo: 484, reviews: 1184, lastByte: 1168.5 }; console.log(`Photo on screen ${allAtOnce.photo - inOrder.photo} ms sooner`);console.log(`Reviews on screen ${allAtOnce.reviews - inOrder.reviews} ms sooner`);console.log(`Last byte of the HTML ${(allAtOnce.lastByte - inOrder.lastByte).toFixed(1)} ms apart`);
  • Lines 2 and 3 hold three times from each way: the photo on screen, the reviews on screen, and the last byte of the HTML.
  • It prints Photo on screen 976 ms sooner and Reviews on screen 220 ms sooner.
  • Then it prints Last byte of the HTML 2.0 ms apart.

The top of the page reached Asha at 417.4 ms. Chrome painted the name at 476 ms and the photo at 484 ms. The photo had already arrived, thanks to the head's preload. Even the reviews came 220 ms sooner. All at once, the first paint had to wait for the stylesheet, as lesson 5.5 showed. In order, it was already in.

Now look at the last line. The HTML finished at the same moment either way. The server wasn't any faster. It just stopped holding back what was ready. Why it matters: streaming doesn't make slow data faster. It stops slow data from hiding the fast parts.

The four ways to scale, in ms after Asha opened the page. All at once: first byte at 1,167.9 ms, photo on screen at 1,460 ms, reviews on screen at 1,404 ms. Head first: first byte at 167.2 ms, photo on screen at 1,244 ms, reviews on screen at 1,244 ms. Streamed in order: first byte at 166.7 ms, photo on screen at 484 ms, reviews on screen at 1,184 ms. Streamed out of order: first byte at 166.5 ms, photo on screen at 480 ms, reviews on screen at 1,188 ms.All at onceHead firstStreamed in orderStreamed out of order0 ms500 ms1,000 ms1,500 msto the first byteto the photoreviews on screen
The shaded part is the wait for the first byte. The bar ends when the photo was on screen. The tall mark is the moment the reviews were on screen.

How the pieces travel

How does the browser know the answer isn't over? The server never said how long it would be. Over HTTP/1.1, it uses chunked transfer coding. RFC 9112 says it sends the content "as a series of chunks, each with its own size indicator". A chunk of size zero marks the end. HTTP/2 and HTTP/3 send DATA frames instead. Either way, the server can pause and go on as often as it likes.

Inside Chrome's parser

Chrome's parser reads whatever bytes have arrived. Then it stops and waits for more. While it waits, the browser can lay out and paint. On a long page, the parser also pauses on its own. In Chrome 157's html_document_parser.cc, it first reads for at most 10 ms at a time (lines 212 to 217). Once it has paused more than 6 times, the limit grows to 500 ms (lines 192 to 232). On Android, those numbers are 2 pauses and 50 ms. A comment says this is "to allow a quick first contentful paint" (lines 742 to 745). Inside the head, it only pauses to start fetching files (lines 815 to 820).

Pick a way to see each piece that reached Asha:

Playground: the pieces that reached Asha
In order: the middle of 5 loads
  1. First byte166.7 ms
  2. Piece 1: the head166.5 ms, 227 bytes
  3. Piece 2: the top of the page417.4 ms, 297 bytes
  4. Piece 3: the reviews and the line about the tea, to the end of the page1,165.6 ms, 683 bytes
  5. First paint476 ms
  6. Photo on screen484 ms
  7. Reviews on screen1,184 ms
  8. Last byte of the HTML1,168.5 ms
Try it yourself
Streamed in order

Pick a way. Each piece is the HTML that reached Asha's browser together, with when its last byte arrived and its size, gzipped. The top of the page is the photo, the name and the buy box.

Chrome 157, a server that plays Fast 4G, a CPU 4 times slower.

Out of order: a fallback now, the reviews later

Streaming in order has a limit. The browser reads HTML from top to bottom, so the server must send it that way too. Ravi's page has a line about the tea below the reviews. It was ready at 250 ms. But it waited behind the reviews, and reached the page at 1,167.1 ms.

On Ravi's page, that line sits below the screen, so Asha didn't notice. But slow data can sit anywhere: a delivery date in the buy box, or a rating under the name. Then everything below it waits.

Real-life analogySaving a seat at the cinema

Your friend is late for the film. Nobody stops the film for her. You put your coat on the seat next to you, and the film starts for everyone. When she arrives, you move your coat, and she takes the seat you saved.

In real life: Your coat on the seat
In web performance: The fallback: a placeholder for the reviews
In real life: The film starting for everyone
In web performance: The rest of the page, sent at once
In real life: Your friend arriving late
In web performance: The reviews, sent at the end
In real life: Moving your coat so she can sit
In web performance: A small script that moves them into place

That's out-of-order streaming. Ravi's server sends a fallback where the reviews go: a placeholder that keeps their place. Then it sends the rest of the page. Here is the middle of the page, as it leaves at 250 ms:

The fallback, and the line after itHTML
<h2>Reviews</h2><p class="loading" id="reviews-loading">Loading reviews…</p><h2>About this tea</h2><p class="about">Cool peppermint leaves. Packed by hand in Ravi's shop.</p></main>
  • Line 1 is the reviews' heading.
  • Line 2 is the fallback. Its id, reviews-loading, lets a script find it later. The stylesheet gives it a height of 264 pixels, to keep room for the reviews.
  • Lines 3 to 5 are the line about the tea, and the end of main. They don't wait any more.

The reviews come last, after everything else:

The reviews, sent lateHTML
<template id="reviews-ready"><ul class="reviews">…24 reviews…</ul></template><script>  const ready = document.getElementById("reviews-ready");  document.getElementById("reviews-loading").replaceWith(ready.content);</script></body></html>
  • Line 1 holds the 24 reviews in a <template>. The browser reads a template's content, but doesn't show it.
  • Line 3 finds the template.
  • Line 4 replaces the fallback with the template's content. replaceWith() swaps one element for others.
  • Lines 6 and 7 end the page.
Out-of-order streaming. On the left, the HTML in the order it reached Asha: the head, the photo, name and buy box, the Reviews heading with the fallback, and the line about the tea. 751.7 ms later, a template with the 24 reviews and a script. On the right, Asha's page: the script replaces the fallback, Loading reviews…, with the template's reviews.The HTML, as it arrivesthe headphoto, name, buy boxReviews, fallbackAbout this tea751.7 ms latertemplate: 24 reviewsscript: replaceWithAsha's pagephotoMint tea, £4.80ReviewsLoading reviews…About this teathe scriptmoves it here
The HTML still arrives top to bottom. The reviews come last, in a template, and the script moves them into the place the fallback kept.

And here is the server:

The fallback first, the reviews lastJavaScript
async function outOfOrder(response) {  const tea = getTea();  const reviews = getReviews();  response.writeHead(200, { "content-type": "text/html" });  response.write(head());  response.write(top(await tea) + loading() + about(await tea));  response.end(late(await reviews));}
  • Line 6 is the change. Once the tea is ready, it sends the top, the fallback and the line about the tea together.
  • Line 7 waits for the reviews, then sends the late piece and ends the answer.

The line about the tea was in Asha's page at 420.2 ms, 746.9 ms sooner than in order. The fallback was painted with the name, at 472 ms. The reviews took its place at 1,188 ms. Why it matters: with a fallback, slow data only delays its own part of the page, wherever it sits.

Did the page jump when the reviews came? No. Its layout shift score, CLS, from lesson 30.1, was 0. The reviews were taller than the fallback, so the line about the tea moved down. But the tall fallback had already pushed it below the screen. A move that Asha can't see doesn't count.

Suspense boundaries in React and Next.js

You don't have to write fallbacks and scripts by hand. In React, a <Suspense> boundary does it. Here is Ravi's page in React:

The reviews in a Suspense boundaryJSX
<main id="app">  <TeaTop />  <h2>Reviews</h2>  <Suspense fallback={<p className="loading">Loading reviews…</p>}>    <Reviews />  </Suspense>  <h2>About this tea</h2>  <About /></main>
  • Lines 4 to 6 are the boundary. fallback is what to show while Reviews waits for its data.
  • Everything outside a boundary is the shell. Here, that's the top of the page, both headings and the line about the tea.

To stream it, Ravi's server calls React's renderToPipeableStream:

Start sending when the shell is readyJSX
const { pipe } = renderToPipeableStream(<Page />, {  onShellReady() {    response.statusCode = 200;    pipe(response);  },});
  • Line 1 starts rendering the page.
  • Line 2 is onShellReady. React's docs say it "fires right after the initial shell has been rendered".
  • Line 4 starts sending. Later, React sends the rest "along with the inline <script> tags that replace the HTML loading fallbacks with the content."

The course recorded React 19.3.1 doing exactly that. Here is what it sent, shortened:

What React really sentHTML
<h2>Reviews</h2><!--$?--><template id="B:0"></template><p class="loading">Loading reviews…</p><!--/$--><script id="_R_">requestAnimationFrame(function(){$RT=performance.now()});</script><div hidden id="S:0"><ul class="reviews">…</ul></div><script>$RB=[];$RV=function(a){…};$RC=function(a,b){…};$RC("B:0","S:0")</script>
  • Line 1 is the boundary in the shell. React marks it with comments and an empty template, B:0. The fallback sits inside.
  • Line 2 notes when the shell was painted.
  • Lines 3 to 5 reached Asha 748.8 ms later. Line 3 is the reviews, in a hidden div called S:0.
  • Lines 4 and 5 define two functions. Then $RC("B:0","S:0") moves the content of S:0 into the boundary.

It's Ravi's template and script, with React's names. React adds one rule. When boundaries finish close together, $RC waits until 300 ms after the shell's paint or the last reveal, so they appear together. That's in React's ReactDOMFizzInstructionSetShared.js, lines 16 and 439 to 460. Ravi's reviews came much later than that, so they appeared at once.

Out of order by hand, and with ReactPop out in the code editor (opens in a new tab)JavaScript
// Out of order by hand, and with React, in ms after Asha opened the page. The middle of 5 loads each.const byHand = { firstByte: 166.5, photo: 480 };const react = { firstByte: 418.1, photo: 716 }; console.log(`React's first byte came ${(react.firstByte - byHand.firstByte).toFixed(1)} ms later`);console.log(`React's photo came ${react.photo - byHand.photo} ms later`);
  • Lines 2 and 3 hold Ravi's hand-written page and React's: the first byte and the photo.
  • It prints React's first byte came 251.6 ms later and React's photo came 236 ms later.

Why later? React sends nothing until the whole shell is ready. Ravi's shell held the top of the page, which needs the tea. So React waited 250 ms before its first byte, head and all. The stylesheet and the photo started late too. Why it matters: what you put in the shell decides when the first byte leaves.

React's onHeaders option can win some of that back. Its docs say it gives you the preloads to send "as an HTTP response header or as a 103 Early Hints response." Two more callbacks matter. onShellError fires if the shell fails, before any byte has left. onAllReady fires when everything is done. The docs suggest it "for crawlers and static generation". Then nothing streams.

Next.js uses the same boundaries. A loading.js file next to a page wraps that page in a <Suspense> boundary, its docs say. Its streaming guide adds a warning. If the LCP element is inside a boundary, "it can't paint until that boundary's content is swapped in." So keep the photo in the shell, as Ravi did.

Status codes and headers once streaming starts

Every HTTP answer starts the same way. RFC 9110 says: "Framing and control data is sent first, followed by a header section". The status code, like 200 or 404, is part of that control data. The content comes after it. So the moment Ravi's head left, the 200 had left too.

Real-life analogyA waiter who said “Coming right up”

Asha orders a Rose tea. The waiter says "Coming right up!" and brings a cup and saucer at once. Then the kitchen says there's no Rose tea. The waiter can't take back what he said. He can only come back and apologise. A food critic at the next table wrote down his first words.

In real life: "Coming right up!"
In web performance: The 200 status, sent with the first bytes
In real life: The cup and saucer on the table
In web performance: The head, already sent
In real life: No Rose tea in the kitchen
In web performance: The database finds no such tea
In real life: The apology
In web performance: A message in the HTML
In real life: The critic's notebook
In web performance: A crawler, which records the 200

First, slow data that fails. The course turned off Ravi's reviews service. The out-of-order page sent its 200, and Asha got it at 166.9 ms. Then, 1,000 ms after the request arrived, the reviews service failed. So the server sent a note in the template instead of the reviews. The same script put it where the fallback was. Asha saw it at 1,184 ms.

When the status left, to scale, in ms. Reviews fail: the 200 reached Asha at 166.9 ms. The reviews service failed 1,000 ms after the request reached Ravi's server, and the note was on screen at 1,184 ms. Rose tea with the head flushed first: 200 at 168.4 ms. Rose tea checked first: 404 at 417.4 ms.Reviews fail200reviews failnoteRose tea, flushed200Rose tea, checked4040 ms400 ms800 ms1,200 mswaiting for the status
Each status leaves with the first byte. The reviews failed long after the 200 had left, so only a note could follow. Checking Rose tea first cost about 250 ms, but its answer was a real 404.

A crawler sees something else. A crawler is a program that reads pages for a search engine. Some run no JavaScript. The course asked for the failing page the way such a crawler does:

The failing page, read without JavaScriptJavaScript
const response = await fetch(`${shop}/fails/mint-tea.html`);
const html = await response.text();
console.log(response.status);
console.log(html.includes("Loading reviews…"));
  • Line 1 asks for the page. shop holds the address of the course's server.
  • Line 3 prints 200.
  • Line 4 prints true. Without the script, the fallback stays where the reviews go. The note sits unused in the template at the end.

For reviews, a 200 is fair. The page is still useful without them.

A missing tea is different. Asha follows an old link to Rose tea, which Ravi no longer sells. The right answer is a 404: not found. But a server that flushes its head first has already said 200. All it can do is say sorry in the HTML. Google calls that a soft 404. Its docs say that for a 200 page with "an error message, Search Console will show a soft 404 error."

Next.js meets the same wall. Its docs say that when notFound() runs mid-stream, "Next.js cannot go back and change the status to 404." It adds <meta name="robots" content="noindex"> instead, so search engines leave the page out. A redirect() mid-stream "becomes a client-side redirect". The fix is to check first:

Check the tea before the first byteJavaScript
async function teaPage(response, slug) {  const tea = await getTea(slug);  if (!tea) {    response.writeHead(404, { "content-type": "text/html" });    return response.end(head() + sorry());  }  response.writeHead(200, { "content-type": "text/html" });  response.write(head());  // ...then stream the rest, as before}
  • Line 2 waits for the database, 250 ms, before any byte leaves.
  • Lines 3 to 6 answer 404 if the tea doesn't exist.
  • Lines 7 and 8 start streaming only when the tea is real.

The course asked for Rose tea both ways. Flushed first, the status was 200, at 168.4 ms. Checked first, it was 404, at 417.4 ms. Why it matters: the check cost about 250 ms of first byte. Pay it only where the status depends on data. Next.js gives the same advice: "Run the corresponding check before streaming starts".

Headers follow the same rule. A cookie or a redirect needs a header, so it must be decided before the first byte. Read each row across:

What Ravi's server can still change
What Ravi's server wants to sendBefore the first byteAfter the first byte
A 404 for a tea Ravi doesn't sellIt sends a 404 status.It can't. The 200 has left, so it can only say so in the HTML.
A redirect to the sign-in pageIt sends a redirect status, such as 302, and a Location header.It can only send a script that moves the page in the browser.
A cookie, from what the database saidIt adds a Set-Cookie header.It can't. The headers have already left.
A note that the reviews failedIt can pick an error status, or put the note in the page.It puts the note in the HTML, where the reviews would go.

HTTP does allow fields after the content, called trailers. RFC 9110 says they can carry "post-processing status information". But lesson 14.2 found that Chrome ignores a Server-Timing trailer. So don't count on a trailer for anything the browser must act on. React's docs add one more rule: "once you emit the shell and start streaming, you can't change the status code."

Pick a visit to see what Asha and a crawler each got:

Playground: what a visitor and a crawler get
Reviews fail
  1. The status200
  2. The crawler got the status at175.2 ms
  3. What Asha seesThe page, with "Reviews can't load right now. Please try again later." under Reviews, from 1,184 ms.
  4. What a crawler without JavaScript readsA 200, and "Loading reviews…" where the reviews go. The note is only inside the template at the end.
Try it yourself
Reviews fail

Pick a visit. The crawler is Node.js's fetch, which reads the whole answer and runs no JavaScript.

Chrome 157, a server that plays Fast 4G, a CPU 4 times slower.

Layers that undo streaming

Streaming only works if every layer between the server and Asha passes the pieces on. Many hold them back. Next.js's guide warns: "Any layer between your server and the client that buffers the response can diminish the benefits of streaming."

Real-life analogyA post room that waits for the last page

You send a long letter to a friend, one page at a time, as you write each one. But your office's post room holds every page until the last one comes. Then it sends them all together. Your friend gets the whole letter at once, as late as if you had never split it.

In real life: Each page you send
In web performance: Each piece of streamed HTML
In real life: The post room
In web performance: A proxy, a CDN or a compression layer
In real life: Holding pages until the last one
In web performance: Buffering the whole answer
In real life: The whole letter at once
In web performance: One late answer

The course tried two such layers on the out-of-order page:

The same page, through three kinds of layerPop out in the code editor (opens in a new tab)JavaScript
// The out-of-order page through three kinds of layer, in ms. The middle of 5 loads each.const ways = [  ["Nothing in between", 166.5, 480],  ["A proxy that buffers", 1167.7, 1464],  ["gzip without flush", 166.7, 1460],];for (const [way, firstByte, photo] of ways) console.log(`${way}: first byte ${firstByte} ms, photo ${photo} ms`);
  • Lines 3 to 5 hold each layer: the first byte and the photo.
  • Line 7 prints Nothing in between: first byte 166.5 ms, photo 480 ms, then A proxy that buffers: first byte 1167.7 ms, photo 1464 ms.
  • The last line is gzip without flush: first byte 166.7 ms, photo 1460 ms.

The proxy held the whole answer until the server ended it. So Asha got it at 1,167.7 ms, like the page sent all at once. Nginx, a common proxy, buffers by default. Its docs say that with buffering off, "the response is passed to a client synchronously, immediately as it is received." A server can turn buffering off for one answer with the header X-Accel-Buffering: no.

The second layer is sneakier. Its first byte came at 166.7 ms, as if it streamed. But that first piece held no HTML. It was only gzip's own 10-byte header. gzip kept the rest until the answer ended. Why it matters: a fast TTFB doesn't prove that a page streams. Check when the content arrives.

Compression needs a flush after each piece:

gzip that sends each piece at onceJavaScript
const gzip = createGzip();gzip.pipe(response);gzip.write(head());gzip.flush();
  • Line 1 makes a gzip stream. Line 2 sends what comes out of it to Asha.
  • Line 3 writes the head into it.
  • Line 4 asks gzip to send what it has now. Node.js's docs say flush() "will make zlib return as much output as currently possible". Without it, gzip waits for more.

React does this for you. Its Node.js code calls flush() whenever it has nothing more to send right now (ReactServerStreamConfigNode.js, lines 38 to 46). A comment there says Express's compression middleware adds that method. CDNs and serverless hosts can buffer too, so check their docs for streaming.

Here is every way the course recorded. Read each row across:

Ravi's page, sent eight ways, on Asha's computer
WayFirst byte (TTFB)First paint (FCP)Photo on screen (LCP)Reviews on screen
All at once1,167.9 ms1,404 ms1,460 ms1,404 ms
Head first167.2 ms1,244 ms1,244 ms1,244 ms
Streamed in order166.7 ms476 ms484 ms1,184 ms
Streamed out of order166.5 ms472 ms480 ms1,188 ms
React with Suspense418.1 ms664 ms716 ms1,192 ms
Out of order, reviews fail166.9 ms472 ms480 msNever. The note: 1,184 ms
Out of order, behind a buffering proxy1,167.7 ms1,396 ms1,464 ms1,404 ms
Out of order, gzip without flush166.7 ms1,400 ms1,460 ms1,400 ms

Stream it, check first, or fix the layer?

Each card is a problem on a shop's pages. Sort it by the fix it needs:

Stream it, check first, or fix the layer?
  • "You might also like" teas from a slow service, near the bottom of the page
  • A delivery date from a courier's slow service, inside the buy box
  • A blog post whose address might not exist
  • An account page that must send visitors who aren't signed in to the sign-in page
  • A cookie the server sets from what the database says
  • nginx in front of the server, with its default settings
  • Compression middleware that never flushes
  • A CDN that holds whole answers before passing them on
Try it yourself
0 of 8 correct

Sort each problem by the fix it needs.

Choose a category for every card. You can change an answer at any time; Reset clears them all.

Common mix-ups

  • "Streaming makes the server faster." No. The HTML ended at about the same moment every way. Streaming only sends what's ready sooner.
  • "Flushing the head is enough." No. The stylesheet and the photo arrived early, but the screen stayed blank until the body came at about 1.2 seconds.
  • "Out of order means the browser reads the HTML out of order." No. It reads top to bottom. The server sends the late part last, and a small script moves it into place.
  • "React streams the head at once." No. It sends nothing until the shell is ready. Ravi's shell needed the tea, so React's first byte came at 418.1 ms.
  • "A server can still send a 404 after streaming starts." No. The status left with the first bytes. It can only say so in the HTML.
  • "A fast TTFB proves the page streams." No. With gzip that never flushed, the first byte came at 166.7 ms, but the photo only at 1,460 ms.
  • "A fallback of any size is fine." No. When the reviews failed, the short note replaced the tall fallback. The line about the tea moved up into view: a layout shift of 0.0124.

Practice exercises

Answer first, then use the hints.

Exercise 1 · Warm-upA slower reviews service

Ravi's reviews service gets twice as slow. What does the first line print?

Starter codePop out in the code editor (opens in a new tab)JavaScript
// The reviews service now takes 2,000 ms. The trip still takes 165 ms.
const trip = 165;
const tea = 250;
const reviews = 2000;

console.log(`All at once: first byte at ${trip + Math.max(tea, reviews)} ms`);
console.log(`In order: the photo's piece at ${trip + tea} ms`);

Answer, then press Check. Spacing and letter case don’t matter.

    Exercise 2 · Warm-upPieces in page order

    This small model sends each piece in page order, as soon as it and the pieces above it are ready. What does the last line print?

    Starter codePop out in the code editor (opens in a new tab)JavaScript
    // A server writes its pieces in page order. Each is ready at its time, in ms.
    const pieces = [["head", 0], ["top", 250], ["reviews", 1000], ["about", 250]];
    let sent = 0;
    for (const [name, ready] of pieces) {
      sent = Math.max(sent, ready);
      console.log(`${name} sent at ${sent} ms`);
    }

    Answer, then press Check. Spacing and letter case don’t matter.

      Exercise 3 · PracticeThe weight of the top of the page

      Streamed in order, how many bytes did the piece with the top of the page weigh?

      Answer, then press Check. Spacing and letter case don’t matter.

        Exercise 4 · PracticeReact at 700 ms

        At 700 ms, what did the React page show Asha?

        Answer, then press Check. Spacing and letter case don’t matter.

          Exercise 5 · ChallengeThe template after the swap

          Open the course's copy of the out-of-order page, out-of-order.html. After it has loaded, is <template id="reviews-ready"> still in the page?

          Answer, then press Check. Spacing and letter case don’t matter.

            Exercise 6 · ChallengeA cookie after the head

            Ravi sets a cookie once he knows the tea. What happens on line 5?

            Starter codePop out in the code editor (opens in a new tab)JavaScript
            async function teaPage(response) {
              response.writeHead(200, { "content-type": "text/html" });
              response.write(head());
              const tea = await getTea();
              response.setHeader("set-cookie", `last-tea=${tea.slug}`);
              response.end(top(tea) + about(tea));
            }

            Answer, then press Check. Spacing and letter case don’t matter.

              Check your understanding

              For each question, ask yourself what was ready, and what had already left the server.

              The streaming HTML quiz · 7 questionsScore: first tries count
              1. Question 1 of 7What does the first line of the opening example print?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // Asha opens Ravi's Mint tea page, sent four ways. Times in ms after she opened it.
                // The middle of 5 loads of each way.
                const ways = [
                  ["All at once", 1167.9, 1460],
                  ["Head first", 167.2, 1244],
                  ["In order", 166.7, 484],
                  ["Out of order", 166.5, 480],
                ];
                for (const [way, firstByte, photo] of ways) console.log(`${way}: first byte ${firstByte} ms, photo ${photo} ms`);

                Choose an answer to see the explanation.

              2. Question 2 of 7In the recording, why did the head-first page stay blank so long, though its stylesheet and photo had arrived early?

                Choose an answer to see the explanation.

              3. Question 3 of 7A page is streamed in order, and a slow part sits in the middle. What happens to the fast parts below it?

                Choose an answer to see the explanation.

              4. Question 4 of 7How does the out-of-order page put the reviews where the fallback was?

                Choose an answer to see the explanation.

              5. Question 5 of 7In the recording, why did React's first byte come later than the hand-written page's?

                Choose an answer to see the explanation.

              6. Question 6 of 7Ravi's head-first server learns that Rose tea doesn't exist. Why can't it answer 404?

                Choose an answer to see the explanation.

              7. Question 7 of 7In the recording, the gzip-without-flush page had a fast first byte. Why was its screen still blank for over a second?

                Choose an answer to see the explanation.

              Key takeaways

              • Streaming sends each piece of HTML as soon as it's ready. Here, the photo came about a second sooner.
              • Flushing the head gets the stylesheet and the photo moving, but nothing paints until the body comes.
              • In order, everything below a slow part waits. Out of order, a fallback keeps its place and the rest goes first.
              • React's Suspense sends the fallback, then the late HTML with a script that swaps it in. Its first byte waits for the shell.
              • The status and the headers leave with the first byte. Decide a 404, a redirect or a cookie before it.
              • A proxy, a CDN or gzip without flush can hold the whole answer back. Check when the content arrives, not just TTFB.

              Remember the one-liner.
              Send what's ready, keep a place for what isn't, and decide the status before the first byte.

              Sources

              The facts on this page come from these standards, docs and source files:

              Coming next: Hydration strategies. A streamed page can paint early. Next, you measure the ways frameworks make it answer taps: all at once, piece by piece, or only where it's needed.

              CompleteFrontend Clear concepts. Working examples.