GraphQL in the World of React Server Components

Welcome, everyone, to React Advanced 2024. My name is Gerald Miller, and I am a principal software engineer at Apollo working as a full-time maintainer on Apollo Client. And hi, everyone, my name is Alessia Bellisario, and I'm a staff software engineer at Apollo also working on Apollo Client.

And I thought we would start by going back in time to last year's React Advanced London in 2023, when Gerald and I delivered a talk called How to Use Suspense and GraphQL with Apollo to Build Great User Experiences. Now, at the time, React server components were on everyone's mind, but discussing them was an explicit non-goal of our talk that showcased how to use suspense effectively with Apollo Client. And I'll just note, you can feel free to come back and use the QR code on this slide to look it up if you want to watch it later.

So, while we didn't focus on RSE last year, this year we'd like to bring you GraphQL in a world of server components. Let's talk about how and why you might pair these technologies and what this stack enables. To start, we'll pose the question that we had on our minds when we first got a glimpse of the new server components paradigm. We honestly wondered the same thing when we set out to provide some compatibility with server components and Apollo Client. And after a year, we can confidently say, yes, GraphQL does have a place in a world of server components. Thank you so much for coming to our talk. That'll be all for today.

No, but seriously, we've been really pleasantly surprised by how much GraphQL combined with server components has been adopted in the last year. And that's reflected in this trend line and this NPM download chart that we see here. This trend line has been continuing on this upward trajectory since really since day one, as we've seen more and more teams using this technology and using it in production with great results. So there's clearly something here. And this is early evidence that engineers love building with these technologies.

Yeah, but you may notice if you take a look at that screenshot there that we've released this under a different package name, you might be asking, like, why is there a need for a separate package? Why not just build this all into Apollo Client Core? And really, the answer is because working with RSC, there's just some different things that we need to keep in mind and just some paradigms that we need to keep track of. So, for example, in server components, it's a best practice that you create your client instances once per request. And the reason for that is because you don't want multiple requests between multiple users to share a cache where you might have data mixing and matching together. That can result in leaked data between your users and could result in maybe some security implications. So we provide some of the utilities to make sure that that happens correctly. And on the client component end, the data that we fetch in the client components is streamed from the server to the browser and used to hydrate the cache on the browser end. And this really helps avoid the requests on the browser themselves since we're already doing the work on the server. If you're really curious about diving into more details, because we're not going to cover too much of the explicit what's going on, I'd highly encourage you to take a look at Lenza's talk from React Advanced last year that digs a little bit deeper into more of the specifics of this library.

Ok, so let's set the table here and talk about what are server components and answer that question. Now, there's so many excellent primers on React server components out there, including Josh Como's blog post, Making Sense of React server components, from which we borrowed the idea for these diagrams. And I've linked that blog post using the QR code in the corner. And you should definitely check it out. Check out Josh's post if you'd like to read more. But here we see the lifecycle of a typical request made to an app, a React app that's using client-side rendering. So when a request comes in from the client, the server or even a CDN will reply with an HTML document that contains a script tag that tells the browser where to fetch the JavaScript bundle necessary to render your app. And this bundle contains your application code and also all the library code that your app needs to render anything to the screen. So once we see that we've downloaded the JavaScript and the browser has parsed that JavaScript, your application code can begin executing. And it's then that any data fetching that's done during render can actually begin. So this might be a fetch call to an API that executes a database query, for example. It's only when that request comes back with data that your app can render content to the screen. So you can imagine the spinners that a user might see here. Now, with server-side rendering, your React application can perform its initial render on the server, which is a nice optimization. Maybe this is just the application shell, or maybe if you're using a meta framework like Next.js, the initial server render can also include some data fetched on the server that gets injected via props for that initial server render pass. But in general, most data will be fetched on subsequent navigations in the browser after hydration that we see in the client, at which point we have the same need to traverse that client server boundary when we make a client fetch for some data that we need from the server. And it's worth noting here that Apollo Client also provides APIs for bootstrapping your cache on the server and performing that initial server render.

So this is a well-tested technique and approach. But with React Server Components, React introduced a new primitive, and that is this new server component that only renders once on the server. So its dependencies are guaranteed to never end up in your client bundle and you can execute server-only code, like connecting directly to a database that we see here.

It's also worth mentioning that under this model, client components is a bit of a misnomer, since client components are also rendered on the server during an initial server-side rendering pass. But you might be wondering, like we're talking about databases a lot, like where does GraphQL actually fit into our overall application architecture? So we can take a look at this diagram here, and really this you start to see this like when your product in your organization starts to grow.

So your architecture may start to evolve and resemble something that looks more like this, where your service actually starts to split among many different services and creating a microservice architecture. So you might split your services by function or by team. But really the point here is that you may no longer be talking to a database directly. And this is where GraphQL really shines because it can create that unifying layer between all of your microservices and give you a unified API that your clients can talk to. So in this case, our React Server Component application will talk directly to our GraphQL API in order to fetch its data. So let's return to our visualization of our React Server Component request here and a request from client to server where we can now replace that database query with a GraphQL query. And here, if we zoom in a little bit more, we can see in this server render area of our diagram, we have both the React Server Components themselves and client components that do an initial render during that SSR pass on the server.

So I'm going to zoom in a little bit and take a look at fetching data in server components using Apollo Client. So let's take a look at some code here. We're first going to import this register Apollo Client function along with Apollo Client in-memory cache from our Next.js app support package. Using the register Apollo Client function, we require that you create your Apollo Client instance in the callback of that function. So as I mentioned earlier, one of the reasons we needed that additional package is because we want to make sure that our client is scoped to a single request. That way our cache is not shared between multiple requests, i.e. potentially multiple users. Otherwise, we could risk leaking user data.

That register Apollo Client function returns a helper function called getClient that when called, returns our Apollo Client instance scoped to that request. So we can use this to fetch data in our server components. So let's actually take a look at a server component and using this getClient function. So here we have our asynchronous server component. And because we're in the server component, we can just use the await keyword directly and await our request here. The biggest difference between the core Apollo Client package and our app package is really that use of that getClient function to get access to our client instance, in which we can call query on it. We can then use the data returned directly by that request to render the rest of our server component. I just want to point out some best practices when working with server components. What should we put in here versus data fetched in client components? Ideally, you want to put data in here that seldom changes and you really don't want to overlap data in your server components with data fetched in client components. Client components are really meant for interactivity, which means that the cache and the data in that cache changes over time.

If you have data that overlaps between the two, it's really easy for that data to grow out of sync with each other and be out of date. The caches are not shared between your server components and your client components. So you really want to make sure that that data is separated as much as possible.

Thanks, Gerald. Now, let's take a closer look at data fetching in client components. And here's an example of a client component that is where we can instantiate our Apollo Client instance and also set up our Apollo Client provider. And what you may notice here is that at the very top, we have our use client directive to indicate that we're now entering that client component boundary. And we're importing Apollo Next app provider, Apollo Client and in-memory cache from our experimental Next.js app support package instead of Apollo Client. And we also require that you create a make client function that creates a new instance of the client and pass that function into Apollo Next app provider. And remember that React context can't be used in server components. So that's why we have to perform this setup in a client component. But otherwise, a lot of this will look fairly familiar to Apollo Client users out there.

And let's take a look at how we would actually fetch data in a client component. So here we can see again with use client, we're in a client component here where we will be executing this all products query and fetching a list of products from our GraphQL API. And we're able to import use suspense query directly from Apollo Client as we normally would to use this suspense enabled data fetching hook to execute our query in our client component. And what's amazing about this is that this fetch request will actually be initiated during that SSR pass and the data will be streamed to the browser where it will ultimately be rendered.

So to review some best practices for client components here, it's really the inverse of what Gerald spoke of about server components. So here we want to fetch and consume data that may change as a result of mutations and user interactions. And so this is where our app will really be able to benefit from our normalized cache in Apollo Client and we'll be able to rerender and react to cache updates as they occur in the client. And so, again, when you structure your queries, this is where we don't want to have overlapping data fetched between our server and client components because, again, we don't want that to get out of sync. So if we zoom in again at that server render, you'll note that our server components actually render and start fetching before our client components. But as we know, one of the great tenants of performance in React apps is starting your fetch as early as possible. So it'd be really nice if we could start our fetch in our server components, but yet render that data in our client components. So we can actually do this inside of Apollo Client in our server components by using an extra utility returned by that register Apollo Client function. And this gives us back a preload query component that we can use to do exactly this. So we take a look at our example here. We can use this in our server components by wrapping our client components as children. So at the top, you'll see our app component here where our preload query component wraps our all products component, and that all products component is our client component in this example. Something to point out here is that you'll notice that the query passed a preload query and to use the suspense query is the same query. And that's because we want to make sure that the request is shared between the two.

So I should mention, too, that we have another way of reading data from the query, but I'd encourage you to go look at the docs for that because we're not going to be looking at that too much today. So in terms of best practices and using this, I just want to point out a couple of practices here. You don't want to use arbitrary queries and preload query, because, again, the point of doing this is to be able to share that request between your your server component and your client component. So those queries are meant to be shared between each other. And much like client components, we don't want to overlap data rendered by a server component. So, yes, it is fetched by a server component, but because it is rendered by a client component, the same principle applies. It's really easy for your cache and the data to get out of sync if you're rendering that data in both. So just make sure that the data fetched by preload query is really meant for your interactivity and those client components.

All right. Now, let's take some of those concepts and see how they apply in an application. So here's an experience that we might have in our app. Now in this wireframe, the green boxes represent server components that are rendering data that rarely changes. And our more interactive content is rendered by a client component, which eventually loads in. But what happens when the query that our client component is making takes a while? Let's look at this example again, but with real timing in here. So that took three seconds for that query to resolve and the data to be streamed to our client components that ultimately rendered it.

And this is the GraphQL query that is backing this UI. So in our all products query, we're fetching a list of products and all of these fields, the ID, the title, media URL to show that image and a list of reviews that contain product ratings. And through some telemetry, we've identified that the reviews are the slowest field in our query. And again, this is one of the strengths of GraphQL in that it allows you to make a single network request for all of the data needs for your UI. But the flip side of that is that your query is going to be as slow as its slowest fields. And so here we know that we could render the rest of our product information much sooner, but we have these reviews that are slowing us down. So can we do better here?

And then we'll let our reviews kind of stream in later. And so we know that React provides a way to to mark parts of our subtree with loading states by adding additional suspense boundaries. But that also means that we need those components to suspend. So what might we actually do here? Ideally, we'd like to stick with a single network request so that we can avoid, in this case, an end plus one query problem. We don't really want to execute additional fetches for those reviews for each of those products. So let's take a look at what GraphQL might be able to do to help us here.

So let's take a look at what GraphQL might be able to do to help us here. So first, we're going to dig into fragments a little bit and talk about what those are. So for those that aren't familiar with GraphQL, fragments, fragments are essentially reusable units and they're a subset of fields that let us split our complicated application data into smaller chunks. This can be really useful if you want to combine lots of UI components together into a single data fetch where each of those fragment defines data requirements for a component.

And here's what it looks like syntactically. So on the bottom, you see our fragment definition, which includes the fields that we want to include as part of that fragment. So in this case, it's that reviews field that you see there. We can include that fragment in our query using that spread like syntax that you see above. So this just makes sure that the fields in that fragment are fetched as a part of our query.

And here is how that query and the fragment that it contains can map onto the components that we're rendering. So here we can see the title and media URL where those are rendered and and the reviews which are rendered beneath. And again, to to the point that Gerald made around how fragments can allow you to scope those data needs of a specific component. This is where we'll see our product reviews component that are rendering the stars. Just declaring that that data requirement through the use of a fragment and Apollo clients use fragment hook.

So, you know, in this case, all products are rendered beneath and all reviews are rendered beneath. So, you know, in this case, all products is fetching all of the data that this UI needs. But product reviews is rendering the reviews data using that use fragment hook. And it's worth noting that fragments aren't enough on their own to improve the user experience here, because while they give us a way to include the product reviews, the product reviews components data in our query, we're still waiting for all of the fields to resolve before we can render our page. So let's turn to something else that GraphQL gives us here to solve this problem, and that is the defer directive.

What is the defer directive? So defer allows us to mark a set of fields as deferred within our query. We still get the benefit of a single network request, but defer tells our GraphQL server to stream those deferred fields in later via a multi-part response. And this gives us that ability to stream in data incrementally. This can really provide a great experience for situations where some fields take much longer to resolve than others. And this is what it looks like in our query. It's essentially allowing us to annotate that product fields fragment with a defer directive to indicate that all of the fields within product fields can be streamed in at a later time.

So we've learned about these utilities, but how do we actually use this in our application? So let's actually do this and we're going to walk through a demo of this in action. I just want to point out before we go too far that what we're about to show you here is highly experimental. It's not yet released in Apollo Client, but we are working on this functionality and we want to add this to a future release. So we just wanted to be able to get excited about the future with you on the possibilities that using GraphQL in the React server component architecture provides. So let's dig in.

So we know that we can provide additional fallbacks and spinners like loading states in our React components by adding suspense boundaries to our components. So we're going to start by adding a suspense boundary around our product reviews component because what we really want is for that product reviews component to suspend so that we can show some of those details about the product as soon as possible before those reviews stream in later.

Taking a look at our product reviews component, again, we want this to suspend. So we're going to replace useFragment with the useSuspenseFragment hook. And this just provides us the ability to give a suspense enabled fragment where if that fragment has not yet loaded in, we will suspend until it is. And finally, we want to go back to our query and annotate our fragment with that deferred directive so that we can tell it to stream in later.

So let's actually see a demo of this in action and how these changes can work with our application. So this demo here puts all of these pieces together. Here we see a Next.js app using React server components and the app directory that begins fetching our query on the server in our server component using preload query. And that query contains the deferred directive on our ratings fields. And the ratings component here is able to suspend on the client until that chunk is streamed to the browser. So here we see the best of React server components and the best of GraphQL combined and some of the things that become possible. We can maintain the single fetch that GraphQL gives us, but with the power of suspense and defer, that multi-part response can actually be streamed across that server client boundary that enables some pretty amazing user experiences.

So what did we hear today? Today, we talked about how Apollo's Next.js package gives you mechanisms for first fetching data directly in React server components to be rendered by server components, but also a way for preloading with preload query so that you can begin fetching data in RSC that can be rendered in client components. And also, you're able to use Apollo Client's suspense-enabled data fetching hooks directly in your client components where that fetch will actually be initiated on the server and the data will be streamed to the browser where it's rendered. And finally, coming soon, you'll be able to use suspense-enabled fragments and stream and render multi-part chunks to the browser. And finally, we're also working on supporting other meta frameworks built on RSC. So with all that said, that's all we have today. Thank you so much. Thanks, everyone.