Suspense Boundaries in Streaming SSR
You'll learn how Suspense boundaries enable streaming by allowing the shell HTML to send immediately while async content loads separately.
The Core Problem with Traditional SSR
When we introduced streaming SSR with renderToPipeableStream, we gained the ability to send HTML in chunks. But without a mechanism to mark "waiting points," the server would still have to wait for everything to complete before sending anything useful. That's where Suspense boundaries come in.
How Suspense Enables Streaming
A Suspense boundary is a dividing line in your component tree. It tells React: "The content inside here might take time to load. Send everything else first, and stream this part when it's ready."
<html>
<body>
<Header /> {/* Ready immediately */}
<Suspense fallback={<Spinner />}>
<SlowDataComponent /> {/* Will stream in later */}
</Suspense>
<Footer /> {/* Ready immediately */}
</body>
</html>
When the server renders this, React sends the shell (Header, Spinner, Footer) immediately via onShellReady. The user sees a page instantly. Meanwhile, SlowDataComponent keeps loading on the server. Once ready, React streams in the real HTML and replaces the spinner—all without a full page reload.
The Analogy
Think of a restaurant where most dishes are ready, but one takes 20 minutes. Without Suspense, the waiter waits until everything is done. With Suspense boundaries, they serve what's ready now and bring the slow dish when it's finished.
Key Takeaway: Suspense boundaries let you mark async parts of your UI so the server can stream the "shell" immediately while slower content arrives progressively, creating a faster perceived load time.