Thinking in React Query

Hello, everyone. Thanks for being here today, where I want to talk about tying your shoes correctly. Most people don't know that there is a right and a wrong way to tie your shoes. Both ways look very similar at first glance, but one knot is stable and the other loosens as you walk. It's a little difference that might change your life. Stay tuned until the end while I show you that trick.

When working with React Query, we might face similar situations, where a small tweak can make a huge difference. I discovered this when I started my open source journey back in 2020, where I was mostly helping out by engaging with the community. I answered a lot of questions on different platforms, which was a great way for me to get started in open source. Turns out people are really happy and grateful if you help them solve their problem. And I also learned a lot by having to look at situations I haven't encountered myself before. With that, I got to know React Query pretty well, and that's when I realized a common pattern among those questions. A lot of them showed an underlying misconception of what React Query is or does and would probably answer themselves with a little shift in thinking.

My name is Dominik and I'm a software engineer from Vienna. I go by the name TK-Dodo online almost everywhere. I work as a front-end tech lead at Edverity and I've also had the privilege to maintain the open-source library React Query for the past two years. So today, what I really want to talk about is showing you three simple ways on how to approach React Query with a better mindset. Similar to tying your shoes correctly, once you know it, it hopefully makes a lot of sense and is quite simple to follow. So let's take a look what it takes to be thinking in React Query.

The first point might surprise you, but it's true. Even though it's often described as the missing piece for data fetching in React, React Query is not a data fetching library. It doesn't do any data fetching for you, because if we take a quick look at a standard React Query example, we can see that we need to provide two things to the UseQuery hook. A unique query key, where React Query will store the data for us, and a query function that will be executed whenever data should be retrieved. We can then, of course, use that hook in a component to render data and the various states the query can be in. But if we take a quick look at the query function again, we can see that in this example, it's implemented with Axios, because why not? But the point is, that is your data fetching library. That query doesn't care how you do it. The only thing it cares about is if you're returning a fulfilled or rejected promise. In fact, and this is probably me talking as a library maintainer, if you're filing an issue telling me you can't show a reproduction because your API is private, I'll likely be telling you that this is the simplest way to implement the query function. No data fetching at all. All we're doing is return a resolved promise.

Of course, React Query goes very well with data fetching libraries like Axios, Fetch or GraphQL Request because they all produce promises. Once we understand that React Query doesn't fetch data, it hopefully becomes clear that a whole class of questions around data fetching just disappear. Questions like how can I define a base URL with React Query? How can I access response headers with it? Or how can I make GraphQL requests with React Query? All questions around data fetching usually have the same answer. React Query doesn't care. Just somehow return a promise, please.

Okay, once we got that it's only fair to ask, if React Query is no data fetching library, then what is it? My answer to this question has always been an Asian state manager. Now it's important to understand what we mean by Asian state. Tanner Lindsley, the creator of React Query, gave a great talk in May 2020 called It's Time to Break Up with Your Global State. The talk is still very relevant today, so please watch it if you haven't already. The gist of it is that we have, for the longest time, sliced our state into where we need it to live. Do we only need it in one component? We'll probably start out by using local state. Do we need it available higher up the tree? Then we move it up, and potentially pass data down again as props. Do we need it even higher up, or everywhere in our application? We'll likely move it to a global state manager, like Redux or Zustand, which lives outside of React and then distributes it globally to our application. And we've been doing this for all kinds of state, no matter if it's the toggle button we're clicking in our app, or the list of issues we have to fetch over the network. We've treated them all exactly the same. The shift in thinking comes when we split state differently. Not where it is used, but by what kind of state it is. Because state that we own completely, that is synchronously available and always up to date, like when I click that dark mode toggle button, has totally different needs than state that is persisted remotely and asynchronously available, like a list of issues. With aging state or server state, we only see a snapshot in time of when we fetched it. It can get out of date because we are not the only owner of that state. The backend, probably our database, owns it. We have just borrowed it to display that snapshot. You might notice this when you leave a browser tab open for some time and then come back to it. Wouldn't it be nice to automatically see fresh and accurate data? That means we have to keep it up to date somehow because other users can make changes in the meantime as well. And because state is not synchronously available, meta information around that state, like loading and error states, need to be managed as well. So, keeping your data up to date automatically and managing agent life cycles isn't something you would get or need from a traditional all purpose state manager. But since we have a tool that is geared towards agent state, we can make all that happen and more. We just need to use the right tool for the right job.

The second part we need to understand is what a state manager is and why React Query is one. What state managers usually do is making your state available in your app efficiently.

The important part here is efficiently. So put another way, I would frame it as we want updates, please, but not too many. If too many updates weren't a problem, we'd all just stick our state in React context. But it is a real problem, and a lot of libraries try to solve this in various ways, some more magically than others.

Redux and Zustand, two popular state management solutions, both offer selector-based APIs. Those make sure that our components are only subscribed to parts of the state they are interested in. If other parts of the store update, those components don't care. And the principle is that we can call those hooks anywhere in our app to get access to that state, because the libraries make it globally available.

Now with React Query it's really not that different. Except that the part you're subscribing to is defined by the query key. Now wherever we call our use issues custom hook, we'll get updates if something changed in the issue slice of the query cache. And if that isn't enough, we can take this a step further because React Query has selectors as well. Now we're talking fine grained subscriptions, where components are only interested in computed or derived results of what is stored. If we toggle one issue from open to closed, the component that uses the use issue count hook won't rerender because the length hasn't changed. And just like with other state managers, we can and very likely should call use query wherever we need to to get access to that data. This makes all solutions that try certain things like calling use effect to sync data from React query somewhere else or setting data into local state in the on-success callback anti-patterns. All of these are forms of state syncing that take away the single source of truth and are unnecessary because React query is already a state manager. So we don't need to put that state into another one.

Okay, so you might be thinking, now I'm doing this, and I'm calling use query wherever I need to, I got three components, I call use issues three times. But if some of our components are rendered conditionally, like when opening a dialog, or because we have dependent queries, we might start to see a lot of fetches to the same endpoint.

You might be thinking, ah, I just fetched this like two seconds ago. Why is it already fetching again? So you turn to the docs, and you start to turn off everything everywhere and all at once, just to not spam your back end that much. Maybe we should have put our data in Redux after all. Bear with me for a second because there is some logic to this madness.

Why is ReactQuery making all those requests? It brings us back all the way to the needs of async state. It can be outdated. So we want to update it at some point in time. And ReactQuery does this by certain triggers. Window focus, component mount, regaining the network connection and a query key change. Whenever one of these events occur, ReactQuery will re-fetch that query automatically. But that's not the whole story. The thing is, ReactQuery will not do this for all queries. Only for those that are considered stale.

And this brings us to the second important takeaway of the day. Stale time is your best friend. Because ReactQuery is also a data synchronization tool. But that doesn't mean it will blindly re-fetch all queries in the background. This behavior can be adjusted by stale time, which defines the time until data goes stale. The opposite of stale is fresh. So put another way, as long as data is considered fresh, it will be given to us from the cache only without a re-fetch. Otherwise, we'll get cache data and a re-fetch. So only stale queries will be updated automatically. But the thing is stale time defaults to zero. Yeah, zero as in zero milliseconds, so react query marks everything instantly stale. That's certainly aggressive and can lead to overfetching. But instead of arrowing on the side of minimizing network requests, react query arrows on the side of keeping things up to date. Now defining stale time is up to you. It highly depends on your resource and your needs.

There is also no correct value for stale time. If you are querying config settings that will only change when the server restarts, stale time infinity can be a good choice. On the other hand, if you have a highly collaborative tool where multiple users update things at the same time, you might be happy with stale time zero. So a very important part of working with react query evolves around defining stale time. Again, there is no correct value. What I like to do is set a default globally and then potentially override it when needed.

Okay, so let's quickly go back to the needs of async state one more time. We know that react query keeps our cache up to date if data is considered stale. And one of these events occur. The one event that is probably the most important of all and that I want to focus on is the query key change event. When would that event mostly occur? Well that brings us to the last point. We should treat parameters as dependencies. I really want to emphasize on this even though it's already outlined in the docs and I also have a blog post about it. If you have parameters, like the filters in this example that you want to use inside your query function to make a request, you have to add them to the query key. This ensures a lot of things that make it great to work with React Query. For one, it makes sure that entries are cached separately, depending on their input. So, if we have different filters, we store them on the different cache keys, which avoids race conditions. It also enables automatic refetches when those filters change, because we go from observing one cache entry to the other. And it also avoids problems with stale closures, which are usually difficult to debug. This is so important, that we've released our own ESLint plugin. It can check if you are using something inside the query function, and tells you to add it to the key. It's also autofixable, so I can highly recommend using it. If you want, you can think about the query key like the dependency array for useEffect, but without the drawbacks, because we don't have to think about referential stability at all. There's no need for useMemo or useCallback to get involved here. Not for the queryFunction and not for the queryKey, because React Query will take care of this for us automatically.

Now, lastly, and this might introduce a new problem. We're now using useQuery wherever we need to at any level in our app, but now we have dependencies to our query that only exist in a certain part of the screen. What if I don't have access to filters where I want to call useIssues? Where is it coming from? The answer again is React Query doesn't care. It's a pure client-state managing problem, because those applied filters are client-state and how you manage that is up to you. It's still totally fine to use local state or a global state manager for that as you see fit.

Maybe writing it to the URL and using that as a state manager is also a good idea. As an example, let's take a look at how this could look like if we've put the filters into a state manager like Zustand. The only thing we've changed is instead of passing filters as inputs to our custom hook, we are getting it from the store directly. This shows the power of composition when writing custom hooks. And we can see the clear separation between service state managed by use query and client state, in this case managed by use store. Every time we update the filter in the store, no matter where, the query will automatically run or read the latest data from the cache, if available. This pattern will enable us to use React Query as a true agent state manager.