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.
- 01Send 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.
- 02Read what React and Next.js sendFollow a Suspense boundary from its fallback to the script that swaps in the late content.
- 03Keep 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:
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:
// 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 msandHead first: first byte 167.2 ms, photo 1244 ms. - The last two are
In order: first byte 166.7 ms, photo 484 msandOut 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?
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
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:
- All at oncea blank page
- Head firsta blank page
- In order
the photo, the name and the buy box, with nothing under Reviews - Out of order
the photo, the name and the buy box, with Loading reviews… under Reviews - Reacta blank page
- Reviews fail
the photo, the name and the buy box, with Loading reviews… under Reviews - Proxya blank page
- No flusha blank page
Move the slider. Each frame is the last one Chrome had drawn by then, in the middle load of each way.
Flushing the head early
Start with lesson 35.1's way. Here is the course's server, sending everything at once:
// 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.allwaits 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()andabout()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:
<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.
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:
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.
// 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 soonerandPhoto 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:
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 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 soonerandReviews 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.
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:
- First byte166.7 ms
- Piece 1: the head166.5 ms, 227 bytes
- Piece 2: the top of the page417.4 ms, 297 bytes
- Piece 3: the reviews and the line about the tea, to the end of the page1,165.6 ms, 683 bytes
- First paint476 ms
- Photo on screen484 ms
- Reviews on screen1,184 ms
- Last byte of the HTML1,168.5 ms
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.
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.
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:
<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:
<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.
And here is the server:
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:
<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.
fallbackis what to show whileReviewswaits 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:
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:
<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 ofS:0into 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 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 laterandReact'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.
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.
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:
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.
shopholds 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:
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
404if 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 wants to send | Before the first byte | After the first byte |
|---|---|---|
| A 404 for a tea Ravi doesn't sell | It 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 page | It 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 said | It adds a Set-Cookie header. | It can't. The headers have already left. |
| A note that the reviews failed | It 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:
- The status200
- The crawler got the status at175.2 ms
- What Asha seesThe page, with "Reviews can't load right now. Please try again later." under Reviews, from 1,184 ms.
- What a crawler without JavaScript readsA 200, and "Loading reviews…" where the reviews go. The note is only inside the template at the end.
Pick a visit. The crawler is Node.js's fetch, which reads the whole answer and runs no JavaScript.
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."
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 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, thenA 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:
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:
| Way | First byte (TTFB) | First paint (FCP) | Photo on screen (LCP) | Reviews on screen |
|---|---|---|---|---|
| All at once | 1,167.9 ms | 1,404 ms | 1,460 ms | 1,404 ms |
| Head first | 167.2 ms | 1,244 ms | 1,244 ms | 1,244 ms |
| Streamed in order | 166.7 ms | 476 ms | 484 ms | 1,184 ms |
| Streamed out of order | 166.5 ms | 472 ms | 480 ms | 1,188 ms |
| React with Suspense | 418.1 ms | 664 ms | 716 ms | 1,192 ms |
| Out of order, reviews fail | 166.9 ms | 472 ms | 480 ms | Never. The note: 1,184 ms |
| Out of order, behind a buffering proxy | 1,167.7 ms | 1,396 ms | 1,464 ms | 1,404 ms |
| Out of order, gzip without flush | 166.7 ms | 1,400 ms | 1,460 ms | 1,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:
- "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
Sort each problem by the fix it needs.
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.
Ravi's reviews service gets twice as slow. What does the first line print?
// 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`);All at once: first byte at 2165 ms. The page sent all at once pays for the slowest data in its first byte. The second line, In order: the photo's piece at 415 ms, doesn't change: the top of the page only waits for the tea.
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?
// 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`);
}about sent at 1000 ms. The line about the tea was ready at 250 ms, but in page order it waits behind the reviews. That's the limit that out-of-order streaming removes.
Streamed in order, how many bytes did the piece with the top of the page weigh?
297 bytes, gzipped. It reached Asha at 417.4 ms, about 165 ms after the tea was ready.
At 700 ms, what did the React page show Asha?
The words, but no photo yet. React's first byte came at 418.1 ms, so the photo was asked for late. It was on screen at 716 ms.
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?
Yes, and it's empty. replaceWith() moved the reviews out of the template's content, into main. The <template> element itself stays at the end of the body.
Ravi sets a cookie once he knows the tea. What happens on line 5?
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));
}async function teaPage(response) {
const tea = await getTea();
response.setHeader("set-cookie", `last-tea=${tea.slug}`);
response.writeHead(200, { "content-type": "text/html" });
response.write(head());
response.end(top(tea) + about(tea));
}Node.js throws ERR_HTTP_HEADERS_SENT: "Cannot set headers after they are sent to the client". A cookie is a header, so decide it before the first byte, as the fixed version does.
Check your understanding
For each question, ask yourself what was ready, and what had already left the server.
Question 1 of 7What does the first line of the opening example print?
Read the code, then predict// 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.
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.
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.
Question 4 of 7How does the out-of-order page put the reviews where the fallback was?
Choose an answer to see the explanation.
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.
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.
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:
- HTML Standard: loading HTML documents, WHATWG.
- Rendering on the Web, web.dev.
- RFC 9112: HTTP/1.1, chunked transfer coding, IETF.
- RFC 9113: HTTP/2, DATA frames, IETF.
- RFC 9114: HTTP/3, DATA frames, IETF.
- html_document_parser.cc, Chrome 157, Chromium source.
- renderToPipeableStream, React.
- ReactDOMFizzInstructionSetShared.js, React 19.3.1, React source.
- loading.js, Next.js.
- Streaming, Next.js.
- RFC 9110: HTTP Semantics, message abstraction, IETF.
- How HTTP status codes affect Google's crawlers, Google Search Central.
- proxy_buffering, nginx.
- Zlib: flushing, Node.js.
- ReactServerStreamConfigNode.js, React 19.3.1, React source.
- response.write(), Node.js.
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.