Let's Build Suspense 🥁

Hi, my name is Julian and I am super excited to be speaking at React Summit this year. Now, 20 minutes isn't a lot of time, so let's get right into it because I want to talk about Suspense. I'm a huge fan of Suspense, basically ever since they started demoing early versions of it in 2016, so quite a while.

But for those of you who don't know, Suspense basically allows you to render boundaries within your application to then render fallback UIs like loading states whenever anything underneath those boundaries is still waiting for promises to resolve. So those could be API calls, but it could also be lazy little JavaScript chunks or any other asynchronous tasks that you're doing in your application. Now, that's pretty cool. But I think Suspense on the server is even more impressive, and I would even go as far as saying it's the unsung hero of React server components because without it, server components the way we know them wouldn't really be feasible. And today, I hope I can show why I think that is and also demystify a few things that are happening underneath the hood.

Now, before that, I want to take a quick look at how we even got to server components in the first place, how Suspense ties into all that just to get everyone on the same page. To do that, we have to take a quick look at the history of web rendering at the last 15 to 20 years. And now, this will make me sound like an old person, but I hope a lot of us still remember the days when we were writing plain HTML and then eventually dynamically creating it on the server with languages like PHP. Now, that came with a drawback, especially if we had to do a lot of work on the server to get that HTML, that initial server response time could be really slow. And that's obviously bad for user experience. So when we started introducing JavaScript to our apps to make them more dynamic, we also introduced concepts like AJAX.

So AJAX allows us to even after the initial server response is finished, to still go back to the server and do stuff. So that means we can offload a lot of that heavy lifting, still have a quick server response, initial server response, and render some kind of loading state while we're going back to the server and fetching more data or whatever we need to do. Right? And that was so convenient that we started doing it more and more until we eventually arrived at what we now know as single page applications. And with it came all the frameworks that we know and love like React, like Vue, like Angular. And to get the best of both worlds, those frameworks very quickly reintroduced the concepts of server-side rendering and static site generation. But we did carry over some of the problems that we had, namely, the first one being the JavaScript bundle size. So ever since single page applications, JavaScript bundles just kept increasing and increasing. And that's not great. And it also caused somewhat like the second problem, which is hydration. So even if your server side render your app, React still needs to send all of the JavaScript to the client and needs to run all of the JavaScript to then hydrate your whole application, just in case some parts of it need client side logic, be it state, be it effects, or event listeners and that kind of stuff. Now, hydration can be really slow. So in fact, that started becoming one of the performance bottlenecks that we're seeing in modern web applications. The third problem is we're back on the server now. So we have the original problem again, where if we're doing a lot of work on the server, that initial response time can get really sluggish. So introduce server components. The main point of server components is for us developers to be able to tell the bundler which components in our application are static, only ever need to be run at once and which components are dynamic and actually need to be run in our client and also need to be hydrated.

So realistically in a normal application, this can massively reduce your JavaScript bundle size and with it massively reduce the amount of hydration that needs to happen after the initial render. But on its own, React server components don't do anything about the third problem. So this is where suspense comes in.

To see how suspense solves the problem, we are going to build our own version of suspense on the server from scratch. Now I want to be very clear here. This is not how suspense is implemented in React. This is intentionally a very dumbed down, a very simplified version of it. The main point I'm trying to make here is to show how suspense works conceptually and also to go through the evolution of what I would call classical server side rendering and to show how we can improve it by introducing something like streaming and then further improve it by introducing what's called out of order streaming, which is what suspense allows us to do.

Alright, enough talking. Let's actually look at some code. And for that, let's pretend we're building a movie application because apparently that's what everyone seems to be doing these days, at least for the demos. And it's called NotFlix because it's definitely not like Netflix and I'm really bad at naming things.

But we can see the page that we're trying to build is pretty straightforward. So we have our logo at the top. Then we have a title section with a poster and the movie title and some meta information like year, genres, and a movie summary. Then we have a scrollable list of the cast members. And at the bottom, we have another list of similar movies because we definitely don't want the user to ever leave our application, right? Cool.

If we look at the code for that, or more specifically, if we look at the components, we can see a few things. So for one, this is the title component, which renders the poster and the summary and stuff. And this is a details component, which renders the customers. And in both, we can see the fetch there and data. So for the purpose of this talk, it doesn't really matter where that data comes from, whether it's a third party API or internally, it could be our own database. What matters is that it's asynchronous. So it will take some time for the data to be there. And we're not in full control over how long that takes.

The other thing that we can see is they're all basically server components. So again, for the purpose of this talk, we only really care about what's happening on the server. And what this means is they can't have anything like state or effects, but they can be asynchronous functions. And for that, it means we can do the data fetching like we do here, right inside of the component, which is convenient.

Now, let's start with what I call classical server-side rendering. And let's look at what the server code for that could look like. We see we have a very basic or standard express setup, and then in our route, we're rendering our application. And then we start collecting HTML. And basically for the app itself, we're just going through all the components that we render, and assume each of those could be a server component. So we execute them as functions, and we await their results. And we turn those into strings. And then at the end, we just concatenate all the strings.

And once we collected all the HTML, we return it back to the server, to the client. And what that looks like, we already seen. This basically uses that render. Right? So it does what we want it to do. But we can also see the problem that I was describing in the very beginning. If we click on one of the links here below, it takes a long time for the browser to actually bring us there. Because the browser has to wait for the server response, before it can actually navigate to the new page. And this is obviously a very bad user experience.

So how can we improve it? The first thing we can do, and I already hinted on that, is introducing streaming. So streaming has been around forever. Basically, since the introduction of the World Wide Web and HTML. And what it does, it allows us to start writing a response, and then keep the connection open, and keep appending to that response document, whenever stuff becomes available. Right? And frameworks like Express and other server frameworks make that really easy. So in Express, on the response object, we have a write method that does exactly that. It writes to the response strip. So let's use that everywhere where we were collecting HTML in memory before. So we don't need that anymore. And use it here. And then we also don't have anything at the end anymore that we need to send, because we've already sent everything. And instead, we just tell the browser, by the response end function, that the connection can be closed. We're finished now. And if we refresh the page, we see that it does what we want.

It immediately renders that logo. But you can also see that there's a problem, and you might have already caught that before, and are screaming at your screen right now. Our sections are all jumped up, they're out of order. And it makes sense. We're still dealing with all of the promises in our components in parallel in this promise all function. So that doesn't really work because in the stream, like I said, we can only ever append to the bottom of the document.

So in order to render the elements in the right order, we have to deal with them in sequence. And I know this is not the most efficient way to do it. But I want to keep things simple for the sake of this demo. So I'll just turn this into a sequential for loop instead of a promise all. And if we refresh the page now, we see it again, renders the logo immediately. And then it renders each of the sections once they become available. Now, this is a lot better than what we started with. But it's still not great, because we're still mostly looking at a blank screen.

So even if you imagine the logo wasn't at the top, but was rendered for whatever reason underneath the title section, we would literally just stare at a blank black screen while the stuff is loading. So that's still not great. So how can we show a loading state to the user while stuff is loading? Now on the client, we could just do suspense here, like render suspense boundary, and render fallback here. So that fallback here, like I said in the beginning, could be some kind of loading state. Then we wrap that around all of our asynchronous components, and that loading state will be rendered while asynchronous stuff is happening. Now let's implement that on the server.

First, we need that component. And that exports the function suspense. Like I said, it has fallback and children. I'm gonna be lazy with types just for the sake of time. But for now, let's just return fallback, just to get us started. And then use that component here. And if we refresh the page, it does exactly what we want. It immediately renders the logo and the fallback. So now we need to keep track of all of those suspended children that we haven't rendered immediately, but that we do want to deal with in the background. Right? So for that, we need a way to keep track of them.

So let's create a simple object we call suspended. And then we need the ability for each suspense instance to have a unique ID. So we know, again, we're just dealing with them on the server, so we can easily do this to make sure each instance has a unique identifier. And then we can use that identifier to store the children that we suspended.

And now, after rendering our whole application, we can actually just check, do we have any entries in that suspended object? So if we just look at the length of that, we know, if any of them are there, basically what we want to do is very similar to what we've done in the classical server side rendering before. Right?

So we want to look at all the entries of the suspended object. Then we make sure that we're actually dealing with an array of React elements. But once we have an array of React elements, we just loop through them again, get their response, turn them into strings, concatenate all of those strings at the end, and then remove that entry from the suspended object because we've dealt with it.

If we run that, we still get the logar and the loading state, but once the content is ready, it also pops into existence. So this is cool. Like now we're really close to what we want, but not quite there.

So the last step that we need is to somehow swap out the loading state for the actual content once it's available. So how can we do that? Like how do we get around the restriction that I described before? We're working with a stream. Stream only allows us to append to the bottom of the document. How do we actually replace a previously rendered element with a new element? So short answer is we can't.

I know that's a bummer, but like most of the things in this world these days, the real magic happens in JavaScript. So we do need a little bit of JavaScript to make this work the way we want it to. And there's basically a few things that we need to make sure we can do. One is we need to actually identify the fallback that we want to swap out because there could be multiple fallbacks. So we need to be able to tell which fallback is the right one for the content that's ready.

So let's wrap the fallback in a div, give it a data attribute that identifies it. Call it suspenseID. That's just the idea that we already have. And now a CSS tip on the side. We don't want this div to mess with the layout of the page. So we can just give it a display of contents, which basically tells your CSS renderer to ignore this div for any layout purposes. So if that is wrapped in a grid layout or a flex layout, this div will be ignored and CSS will look in the children for any layout purposes. So that's pretty cool.

And once we're able to identify it, what we want to do is wrap the actual content in a template. So this will allow us to still add it to the document, but the browser will ignore it. It will not render anything. Let template tag. And the other thing that we want to do is now tell the browser which fallback it should swap it out for, right? So the content is available. We want to swap it into place wherever that fallback was rendered. So there's a billion ways to do that for the purpose of this demo, we are going to do it with web components or more specifically custom elements. So let's pretend we have a custom element called suspense content, and that has a target ID. So this allows us to tell the browser, this is the ID we want to swap it out with. And now we just need to write that JavaScript that does what it does.

So for the sake of time, because I'm running out of it, I'll just copy that from my notes, but I'll still go through it like we're actually doing here. So all we're doing is we're defining a custom element, like I said, calling it suspense content. And this basically allows us to use that as a tech like here. And every time the tag gets rendered, the connected callback function will be called. And in that connected callback function, all we're doing is looking for the previous sibling, which we know is a template element. Then we take the ID from our attributes from the target ID. We use that to in the DOM find the suspense boundary, like our fallback that we rendered with the related ID. And all we're doing is swapping out the HTML of each other. Cool. If we save that, refresh the page, it hopefully does exactly what we want. It shows the loading state, but once the content is there, bang, it gets swapped out with the loading with the, with the actual content. So the loading state is gone, the actual content is there, and we're not limited to a single suspense boundary either. So just like on the client, what we can do is wrap each of our sections in their own suspense boundary to render their own loading state. And was, that gives us is even better UX because now, um, each of them has a loading state and each of them can render immediately once they're ready, they don't have to wait for all of them to be there, which is pretty cool.