https://overreacted.io/progressive-json/
overreactedby Dan Abramov
Progressive JSON
May 31, 2025
Pay what you like
Do you know about Progressive JPEGs? Here's a nice explanation of
what a Progressive JPEG is. The idea is that instead of loading the
image top to bottom, the image instead is fuzzy at first and then
progressively becomes more crisp.
What if we apply the same idea to transferring JSON?
Suppose you have a JSON tree with some data:
{
header: 'Welcome to my blog',
post: {
content: 'This is my article',
comments: [
'First comment',
'Second comment',
// ...
]
},
footer: 'Hope you like it'
}
Now imagine you want to transfer it over the wire. Because the format
is JSON, you're not going to have a valid object tree until the last
byte loads. You have to wait for the entire thing to load, then call
JSON.parse, and then process it.
The client can't do anything with JSON until the server sends the
last byte. If a part of the JSON was slow to generate on the server
(e.g. loading comments took a slow database trip), the client can't
start any work until the server finishes all the work.
Would you call that good engineering? And yet it's the status
quo--that's how 99.9999%^* of apps send and process JSON. Do we dare
to improve on that?
* I made it up
---------------------------------------------------------------------
Streaming JSON
We can try to improve this by implementing a streaming JSON parser. A
streaming JSON parser would be able to produce an object tree from an
incomplete input:
{
header: 'Welcome to my blog',
post: {
content: 'This is my article',
comments: [
'First comment',
'Second comment'
If you ask for the result at this point, a streaming parser would
hand you this:
{
header: 'Welcome to my blog',
post: {
content: 'This is my article',
comments: [
'First comment',
'Second comment'
// (The rest of the comments are missing)
]
}
// (The footer property is missing)
}
However, this isn't too great either.
One downside of this approach is that the objects are kind of
malformed. For example, the top-level object was supposed to have
three properties (header, post, and footer), but the footer is
missing because it hasn't appeared in the stream yet. The post was
supposed to have three comments, but you can't actually tell whether
more comments are coming or if this was the last one.
In a way, this is inherent to streaming--didn't we want to get
incomplete data?--but this makes it very difficult to actually use
this data on the client. None of the types "match up" due to missing
fields. We don't know what's complete and what's not. That's why
streaming JSON isn't popular aside from niche use cases. It's just
too hard to actually take advantage of it in the application logic
which generally assumes the types are correct, "ready" means
"complete", and so on.
In the analogy with JPEG, this naive approach to streaming matches
the default "top-down" loading mechanism. The picture you see is
crisp but you only see the top 10%. So despite the high fidelity, you
don't actually see what's on the picture.
Curiously, this is also how streaming HTML itself works by default.
If you load an HTML page on a slow connection, it will be streamed in
the document order:
This is my article
);
}
async function Comments() {
const comments = await loadComments();
return {comments.map(c => - {c.text}
)}
;
}
Now the user will perceive the loading sequence in two stages:
* First, the post "pops in" together with the header, the footer,
and a glimmer for comments. The header and the footer never
appear on their own.
* Then, the comments "pop in" on their own.
In other words, the stages in which the UI gets revealed are
decoupled from how the data arrives. The data is streamed as it
becomes available, but we only want to reveal things to the user
according to intentionally designed loading states.
In a way, you can see those Promises in the React tree acting almost
like a throw, while acts almost like a catch. The data
arrives as fast as it can in whatever order the server is ready to
send it, but React takes care to present the loading sequence
gracefully and let the developer control the visual reveal.
Note that what I described so far has nothing to do with "SSR" or
HTML. I was describing a general mechanism for streaming a UI tree
represented as JSON. You can turn that JSON tree into progressively
revealed HTML (and React can do that), but the idea is broader than
HTML and applies to SPA-like navigations as well.
---------------------------------------------------------------------
In Conclusion
In this post, I've sketched out one of the core innovations of RSC.
Instead of sending data as a single big chunk, it sends the props for
your component tree outside-in. As a result, as soon as there's an
intentional loading state to display, React can do that while the
rest of the data for your page is being streamed in.
I'd like to challenge more tools to adopt progressive streaming of
data. If you have a situation where you can't start doing something
on the client until the server stops doing something, that's a clear
example of where streaming can help. If a single slow thing can slow
down everything after it, that's another warning sign.
Like I showed in this post, streaming alone is not enough--you also
need a programming model that can take advantage of streaming and
gracefully handle incomplete information. React solves that with
intentional loading states. If you know systems that solve
this differently, I'd love to hear about them!
Pay what you like
---------------------------------------------------------------------
Discuss on Bluesky * Edit on GitHub
overreacted
{post.text}
{comments.map(c =>- {c.text}
)}
; } React will serve the output of the Page as a progressive JSON stream. On the client, it will be reconstructed as a progressively loaded React tree. Initially, the React tree on the client will appear like this:This is my post
{new Promise(/* ... not resolved yet */)}This is my post
{post.text}