How to Use Suspense and GraphQL with Apollo to Build Great User Experiences

What an amazing day. We're so excited to be here with you all in London. And we're going to be talking about how to use suspense and GraphQL with Apollo client and how to build really great end user experiences. But first, let's introduce ourselves very quickly because Amber did a great job already. I don't know if anything's gonna be new said here, but I am Gerald Miller. I am a principal software engineer at Apollo working as a maintainer on Apollo client. And you can find me pretty much everywhere online at my handle Gerald Miller. And I'm Alessia Balissario. I'm a staff software engineer also at Apollo and I'm at AlessBell.

So let's dive right in and talk about what we will be covering today. So this talk is going to be about reintroducing, introducing or reintroducing for some of you, some core React suspense concepts in the context of client rendered web apps and focusing on how to fetch data in suspense with Apollo clients new suspense hooks that we released in August in version 3.8 of Apollo client. And also to talk about what we're not going to cover today. We're not going to be covering React server components or streaming SSR. There's, it looks like there's a lot of sessions here today. We hope that you check out for some of those super cool advances in the React ecosystem. But if you are curious about this space with Apollo specifically, you can check out our experimental Next.js package as you see on screen here. Also shout out to our co-maintainer Lens who's done a lot of the legwork for this here. So if you have questions about this, definitely hit him up. Also what we're not going to be covering is how to actually implement support for suspense in a data fetching library, because it's actually a little more complicated than meets the eye.

Okay, so let's go back in time to 2018 when Andrew Clark, React core team member, sent out this tweet in January 2018. So this was more than a month before Dan Abramov's JSConf Iceland talk titled beyond React 16, which gave a look into the future of React and introduced suspense with some of the first public demos. I think this is a great place to start because Andrew here is talking about certain patterns of interaction that just felt much nicer and still do in many ways on native platforms like iOS compared to the web and the experiences that are most often seen on those platforms.

Andrew wrote, one reason iOS feels nicer than the web, fewer unnecessary loading states. Look what happens here in this screen recording when you tap an option in the settings app. Instead of transitioning immediately and showing a spinner for a split second, it pauses for a moment until the view is ready and that view slides over. Much more fluid. I think this is really prescient, was in 2018, and foretold a lot of where the ecosystem was going in terms of managing these transitions on the web.

Yeah. So, if you've used Apollo for any amount of time, you've probably used this hook quite a few times, useQuery. This is the way you typically fetch data in your applications today. This comes with really two exports that you use most of the time, the data property and the loading boolean that you use to determine when to show a loading state in your components. Just to take a look at a small example here, we've got this little albums component here that uses the useQuery hook to fetch some data and show this loading boolean. No surprise when you tap this button, you see this loading state here. When that loading boolean is true, we get that little bit. When it's done loading, we can see our list of albums here. And so while we just looked at the status quo and that flash of a loading spinner, and we will be talking a lot about loading states today, and how that impacts the UX of our apps that we're building, we really wanted to put a disclaimer out there that React suspense is not just about having a different mechanism for rendering loading states. Just a different API for showing spinners and fallbacks. It really gives us this very composable, very Reacty way of orchestrating and managing these transitions in our apps. So it goes much further than just simple loading states, if you want to think about it that way.

So in terms of Apollo Client, we're here to talk about suspense, and we're talking about suspense in Apollo Client. We're going to be talking about this in the context of a hook we released in Apollo Client 3.8, called UseSuspenseQuery. What is UseSuspenseQuery? Essentially it's a suspenseful version of our UseQuery hook that fetches some data that's integrated with all of the React 18 suspense features, which includes React 18 transitions. So for the majority of the rest of the talk we're actually going to be looking at this in the context of the Spotify clone we built here. And there's a couple of areas on screen that we'll want you to pay attention to as we go through some of these demos here. So you see all these colored boxes on the screen? Each of these represent an area of our UI that has a UseQuery hook that's loading some data from the server. This is really to get an idea of how the status quo today works, and how we can make this better with the UseSuspenseQuery hook and just React 18 suspense. So to get an idea of what the loading UX looks like today, let's go take a look at this here. Yeah, so here we see each of those four components when our app first loads. Again, they're using UseQuery under the hood, and we can see the popcorn effect as the UI loads in.

Each component is responsible for rendering its own loading fallback, and it's going to render data as soon as its network request returns that data. We don't have any greater control over it than that, we're just letting these components render when the data is ready.

It's a bit visually distracting, having those four areas load in entirely dependent on when that network request resolves. So we're going to actually write some code together. We're going to transition this from a UseQuery-enabled app to a UseSuspenseQuery-enabled application.

So we're going to pull up this demo here, and again, like I said, this is what we will be working with today. Just to refresh, this is the exact same experience you saw in that video a second ago. That popcorn effect you see as that data loads in. And just to get oriented a little bit with this application here, here I have my layout here. You can see those colored boxes, each of those components there, the sidebar, the user menu, the route, and the playbar, which each represent one of those areas that load some data.

So we're going to start and actually convert one of these components over to UseSuspenseQuery. We're just going to start with the user menu there, which is that green box in the top right-hand corner. So to do so, here's my component, UseQuery. You see I have my GraphQL query, my UseQuery import, and a pretty familiar site here, that data and loading Booleans. When that loading Boolean is true, we return our loading state, and that's what we see.

So to convert this over to Suspense, I'm going to start by importing UseSuspenseQuery, replace the usage here, and something you're going to notice right away when we make this change is that we get this error here, property loading does not exist on type UseSuspenseQueryResult. And that's because the mechanics of Suspense, we don't actually need that loading Boolean because we're going to let Suspense handle this for us. So it makes no sense, we can actually remove that. And because of that, we no longer need our loading state. Something to also pay attention to here, with this, if I were to take a look at the type of that data property, if you're used to using this with UseQuery, you're used to seeing a union with undefined here as well. With the Suspense enable application, it actually works as if this were a synchronous code. You see our query type here is that UserMenu query type, which is really neat, enables some nice things about this. For this demo, we want to make a change. We like to take baby steps and kind of see what that change does to our application. So let's go back to our application here and refresh it and see what that change did.

Okay, so now we're seeing a blank screen for a split second, and at first paint we see the UserMenu was loaded in there. It was pretty quick, so maybe we can refresh again, Gerald. So you won't see the green highlight around the UserMenu in the top right because by the time our app first renders, the data is present for that UserMenu. So we're fetching the data for our UserMenu with our SuspenseEnabled hook, but we're not showing a loading fallback yet. For that, we're going to need a SuspenseBoundary.

So let's go ahead and add that, Gerald. Let's do it. So I'm going to come over here to my layout, and to add suspense, I'm going to import the Suspense component from React. And then we're just going to wrap this, our UserMenu, here with that. If I can hit the right screen, this is the problem with being so tall on this here. And this is going to take a single prop, which is the component we want to show when the component is suspended. So here, I'm just going to use that UserMenu loading state here. And again, baby steps. Let's go ahead and refresh and see what this change did here.

Great. So now we see the green highlight around the UserMenu as it's in its loading state. But otherwise, everything else is unchanged. I mean, the entire UX is still totally unchanged, right? So let's go ahead and add suspense boundaries and use suspense query to our other three components before we can make a bit more progress here. Awesome. So I'm just going to start in. We'll go to the sidebar here. Same thing that we did with the UserMenu. I'm going to replace my import with useSuspenseQuery. We don't need that loading boolean anymore, which means I can get rid of that loading state in my component. We'll do the same thing with the Play bar here. useSuspenseQuery. Go replace the usage, get rid of the loading boolean. And hopefully you're starting to see a little bit of a pattern here. One of the things we wanted to make sure to do with you suspense query is make it feel very familiar to useQuery in that it's got a lot of the same options and kind of feel that it does. Obviously, the ergonomics of how you manage that loading state is a little bit different. But we're hoping in the majority of cases, switching over to suspense is more or less as easy as this is. So let's get our last one here. useSuspenseQuery. Get rid of the loading boolean. And then in our layout, we're going to add our suspense fallbacks around each of these.

I'm just going to copy this a bunch of times. And then let's make sure each of these use the right loading states here. This one is the play bar. Thank goodness for prettier, otherwise my code would look horrendous.

Okay, so again, baby steps. Let's go refresh this and see what happens. And it's a bit anticlimactic because still nothing has changed, right? Suspense is not a magic wand that we can wave at our code and have the UX improve. All we've done is change the mechanism that we're using to render, to display that loading fallback, to be suspense instead of having our components be responsible for rendering those loading fallbacks.

But now that all of our components are using suspense to show those fallbacks, we have a superpower here because we can reorganize these suspense boundaries. And so let's make the first real substantive change here to the loading experience by wrapping our entire app in a single suspense boundary instead of those four granular boundaries for each component. Awesome. So, like before, I'm going to add a suspense boundary here. This time it's going to be around my entire application. Make sure I use the right loading state here. I'm just going to go delete all of those suspense boundaries that we added before. So now here we have a single suspense boundary around the whole thing. Let's see what this change does to our application here. Ah, tada. So we have a single update to the screen now, just by virtue of being able to move that suspense boundary to the outermost level of our app. And I must say, that's much more pleasing to the eye, having a single paint to the screen with all of our data ready for the user to interact with.

But now let's say we're, you know, we're starting to interact with our Spotify clone here. We want to listen to a different playlist. Gerald why don't we go ahead and navigate around and pick something else to listen to. Yeah, that's great. So my daughter would be psyched if we all listened to her playlist together. So I'm going to navigate here and we see something interesting, which is that I see that suspense fall back, show up when I navigate to another route here. So what might be happening here, Alessia? Yes. So we've gone a bit too extreme in one direction of having a single suspense boundary for our whole app. So by transitioning the route, you know, that that transition and that network requests to fetch a new playlist is triggering that single suspense fallback for our entire application. And, you know, obviously that's not the user experience we want here.

We want to keep that application Chrome, that sort of persistent layout on the screen while our user navigates around and the inner route component suspends. So let's add a second suspense component around our route. Awesome. So I'm going to come in here around the route, which is that component that suspends as we navigate around. Make sure we're using the right component here, route loading state. Let's go into refresh and then we're going to navigate back to our react advanced playlist here. And now we can see where we're back to the user experience that we're looking for. Nice. Yep. This this looks great. And so here we see that, you know, now when we load in our our outer shell of our application unsuspends first, and then there's another slight delay while we continue fetching the route component, which then unsuspends with its data when it's when it's ready to render. But, Gerald, what if the inner suspense boundary, that route components has its data and is ready to render before that outer suspense boundary? Yeah, that's a great question. Invert that. Yeah. Yeah. So to control kind of these timings here that we can see, I'm just going to point out that something you'll notice in our queries here, we're using this at synthetics directive here just to better understand how each of these timings work. So again, we want to see what happens if that playlist route actually loads much faster than our outer shell. So I'm going to delete this synthetics directive and let's go ahead and refresh and see what happens here.

Okay. So if our inner route component is ready to render before the outer shell, now by virtue of using suspense, React is able to coordinate that for us and orchestrate that. So we'll never see the inner suspense boundary before the outer, but it means that, you know, now in the worst case scenario, if our inner route is ready a bit later than our application shell, we'll have two updates to the screen. But on the other hand, in the best case scenario, when it's ready, you know, around the same time or earlier, we'll have a really nice single update to the screen in the best case scenario. And all of that is just by virtue of the power of suspense and using these tools that React gives us, which is really nice.

So now let's see if we were to load some more tracks here. Yeah, actually, first I'm going to go to each of these components, because you probably saw synthetics directives around each of those, and we want to get a better feel for what the actual end user experience is going to look like here. So I'm just going to go to each of these queries. I'm going to delete this here. We'll go to the play bar. Same thing, just get rid of this synthetics directive. We don't want it anymore. And now we see the loading state is much more as you'd expect. There's actually something, though, to point out here, which is that if I refresh this, that playlist that we see here is actually still taking a little bit too long for our liking to load this here. And we want to improve this experience. Now we've done some stuff with suspense, but we also want to do some stuff with GraphQL because GraphQL also gives us some great tools here. So I don't know how many of you have watched any of the spec advances lately, but there is a new stage two directive that is almost ready for mainstream called defer that lets us mark part of our query as something that can be streamed in at a later time. So it gives us the ability to say, Hey, we understand that there might be a slow part of our query here, but we want to get some data faster. And then we'll load in some of that, that slow stuff later. So just pretend we've done some sleuthing and we see that our tracks a field here is the thing that's really taking kind of the longest to load in here and what we'd like to see, we're okay if that tracks loads in a little bit later, but we'd like to see that playlist details just a little bit quicker here so we can use defer. I'm going to use an inline fragment here and let's go ahead and refresh that and see what what defer gives us here. Okay, nice. So now we saw two updates to the screen. We saw that our route component was rendered at the same time as our application shell and those deferred tracks loaded in that second render to the screen, but Gerald, what happens now if our route component is a little bit slower?

Yeah, that's a great question. So let's go back and add our trustee synthetics directive here, if I can spell timeout correctly. Let's add a second latency to this and refresh and see what happens here. Let's try that again. Got to love conference WiFi, right? Or maybe I didn't even save it. Okay, well, what we're still seeing is two updates to the screen. Conference WiFi, I tell you.

Let's see here. Okay, we're still seeing those two updates to the screen. But if our timeout on the route component on our playlist query there was working, what we were going to show in this moment was the change in UX from going to two updates to the screen in the worst-case scenario to three updates to the screen in the worst-case scenario you can imagine our application shell loads in first, then we would have the route component that would unsuspend in a second render to the screen, and then the tracks that are wrapped in defer would be that third update to the screen. So the main takeaway here is really just this idea that adding additional layers of suspense boundaries and loading fallbacks gives you more granular control over this loading UX state transitions in general in your app. But there's a trade-off here. We can show some content sooner to the users in the best-case scenario, but in the worst-case scenario we're going to add additional moments in our app where we're showing loading fallbacks in the worst-case scenario.

So one last thing, we mentioned at the beginning that we integrated the suspense hooks with React 18 transitions. We're going to take a look at that here. Here I have my playlist. I'm going to scroll down because I want to listen to more tracks at the bottom. We see something interesting here, which is that as I scroll and I go to load more tracks, we see that it suspends again and I get a loading fallback here. So how might we look to make this better? Something to point out here is in my playlist, for those of you that have used Apollo for any amount of time, you've used the fetch more API to load data in a paginated query. In this case we're doing an infinite scroll scenario. We've got a fetch more exported from use suspense query that we're calling in this handle load more function. When we call fetch more, it's causing our component to suspend again because we're going back into that loading state. We're going to make this a little bit better by bringing in a transition that allows us to see what we have on screen and avoid that suspense fallback. Before I do so, let's also remove the synthetic directives since we don't want to wait two seconds to load more tracks. To add a transition, I'm just going to import the start transition API from React and we're going to wrap my fetch more call in start transition. This is going to tell React to mark this as a transition. When this component suspends, it's going to leave what we see on screen and avoid seeing that fallback. Let's go ahead and refresh. We'll scroll down here and now we get the UX that we are expecting. Much better. So, what did we learn today? We looked at our Spotify clone starting with use query under the hood and then migrated our data fetching hooks over to use our new suspense enabled hook use suspense query. Then we saw how moving around suspense boundaries in our app could change, drastically impact the loading experience. And then we looked at how to use defer to add additional fallbacks and, you know, deprioritize some of the fields in our query. Then we saw how to mark one of our network requests coming from our fetch more call here as a transition in react to tell react to keep the existing UI on the screen while we make that network request in the background. So that's our demo for you today. Yeah, thank you. Thank you.

Awesome. So, real briefly, we are out of time but unfortunately we didn't get to talk about the whole suspense story. We also released two other hooks in Apollo client 3.8, use background query and use read query to help avoid request waterfalls. So if you're interested in those, check out our documentation or come talk to us after our talk here. Yes, and looking to the future, we're currently working on the next minor version of Apollo client 3.9, which we have planned some exciting new APIs, like a suspenseful version of the use fragment hook, and also a lazy version of use background query that we're calling use interactive query for preloading, prefetching data on some user interaction. If you liked the demo that you saw here today and want to play around with it yourself, feel free to go to this repo, the Apollo GraphQL org, the Spotify showcase, the code for this entire application lives there. And we are planning to use this as a teaching tool and a way to show off some Apollo client best practices, but also as maintainers, we're going to be using it to kind of stress test our own APIs to just really get a feel for what it's like to use it in a complex application. But with that, thanks so much for having us up here. Yeah, thank you.

So let's start with the first one right in the middle here. Okay. So, first one, how would you go about testing suspense? Great question. So I guess it depends on, I'm assuming this person's talking about, like how would you go about testing a component that's using suspense to render its fallback? And the answer is really using the testing tools that are super popular and ubiquitous in the React community, like testing library.

Yeah, to keep my answer short, anything to add? Yeah, I'll just add there, so one of testing library's philosophies is to use the app as your users would expect. So presumably you're already testing some kind of loading state in your application. You know, does my component render whatever spinner or loading text or whatever you have? It's going to be the same thing. It's just your code in that component is going to be organized a little bit differently. But if you're using it as kind of that black box, like the end user experience, really there's not a whole lot to change. Thank you.

And this may be our final question, but again, you'll be able to speak to them around the corner. So final question, how does using a single suspense boundary at the top level affect things like SCP and LCP? And can this be answered in two minutes? Yeah, great question. So the short answer is you probably don't want just a single suspense boundary in your application. You know, maybe there's a certain kind of app that, you know, where you really want to wait for every single initial network request resolved before showing anything at all to the user. the benefit of being able to use that super Reacty composable API that allows you to just compose these things really nicely. So yeah, so again, you would probably if you had a lot of network requests happening in your app and just a single suspense boundary, yeah, that could definitely negatively impact your sort of perceived performance in loading UX, but that's why it's super simple to drop in additional boundaries. Yeah. I think we can squeeze in one more. What do you reckon? Let's do it. Why not? Let's do it. Okay. So you used a user menu loading state pattern. Does every component have a loading state? How does this scale? This seems like a syntactic sugar for non-suspense. Yeah, so that's just the way really I chose to structure this for this demo because it's the easiest to remember. I didn't have to deal with imports because that takes time obviously to write in front of you all. So really, I would say it's up to you, whatever pattern you have today, again, the biggest change we had is we took that loading state that was rendered in our component and we moved it up to a suspense boundary. But I don't know if you noticed that each of those components that rendered with the use query, if loading used that same user menu dot loading state component inside of there. So I really didn't change what component I was using. I just moved it to the suspense boundary rather than rendering it in the component. But again, that's just a pattern I chose specifically for this talk.

It's up to you. However that works in your app. Again, in this particular application too, we've got so many different loading states because they're skeleton screens, but if you've got a single spinner that you use in your application, that may only be one component. So yeah, again, it's with the classic, it depends.

Wow. It is 11.10 on the dot. All right. So much. And we're the timekeeper as well. So thank you so much for your talk.