React Query - The Bad Parts

React Jets Introduction to React Query A short introduction to React Query React Query, the bad part. I really hope this is going to be a quick one, like a lightning talk, really, because I think mostly React Query is just great. I think it's loved by the community for the developer experience and the user experience it provides. I know that's a bold claim, so I tried to bring some evidence to back that up.

If we look at the weekly download numbers on NPM, I think React Query has grown a lot this year from almost 4 million to 6 million weekly downloads. I think those are huge numbers, and if we compared it to the React numbers, which is also, React is growing strong, sitting at about 27 million weekly downloads, all of a sudden the curve doesn't look as impressive anymore, but I think we can still take away from that, that React Query is used in about 20% of our React applications or in almost every fifth app. Some of those apps, they have millions of users themselves, like Sentry, Blue Sky, or JetGPT, so I think React Query really gets a lot of exposure.

Now, of course, download numbers and usage and exposure aren't everything, just because something is used doesn't actually mean that it's liked. So maybe a better way would be to look at surveys. There is the State of Frontend 2024 survey, which asked the question, which tools have you used to fetch data in the last year? Now, I'm not going to nitpick here that React Query is not a data-fetching library, like Axios or Fetch, that are listed here, but behind those, it actually comes in with a very positive sentiment, because only 2.8% of people who used it didn't like it. And State of React has a similar question around utilities for loading and managing data, and if we group that by positive sentiment, then TensorStripe Query actually comes out at the top with a little bit over 44%. So I'm really happy that developers seem to like the library, because I've been maintaining it for the last four years.

My name is Dominic. I'm a software engineer living in Vienna, where I will be joining the frontend platform team at Sentry in the next month. And you can find me as TK Dodo online almost everywhere, and I also have a blog where I write about React and TypeScript, and of course, React Query.

Now, I've written and talked a lot about why React Query is great, and I still think it really is, but, you know, everything is a trade-off. And if we use any technology, it's usually a good trade-off if the thing we are getting in return is worth more to us or is better for us than what we are trading in. Now, I think React Query is really a good trade-off for most situations, but, of course, there are cases where it might not be the best fit or the perfect fit. So today, I want to talk about these cases, but also maybe debunk some myths that I've heard about it that make it sound like it's bad when it actually maybe isn't. So maybe the talk should be more like React Query, the trade-offs.

Okay. Let's get started with the first point, the elephant in the room, which is the bundle size. That React Query has a huge bundle size is something that I often hear as its largest drawback. And to get to the bottom of that, we first have to establish what the bundle size isn't, because it's not what you see on npm, right? This is the size that gets shipped to the developers when they install the library. Yes, it's over 700 kilobytes, but it also includes all the sources and source maps for you to better debug the library.

And we also ship some code mods for the upgrades that we have. This is definitely not the size that gets shipped to the consumer.

Okay. It's also not what you see on Bundlephobia. I think Bundlephobia is a good site to get a quick overview, but it doesn't understand ESM properly, which I think... No, I don't think anybody does that. But, like, we ship a special legacy build for all the bundlers, like Webpack 4, that isn't as optimized, and Bundlephobia picks up on that. So whatever you see here is also still too large. And if you use a more modern bundler, you will get a smaller output.

So I really like Bundle.js to get a good overview, because it just builds what we export on the fly with ESBuild, and then it shows the size impact. So if we export everything from RareQuery, we get to 12.4 kilobytes minzip. Now, that's not nothing, but I also don't think that's a lot. And if we care about size, we should probably use Brotli compression instead of gzip. So if we do that, that gets us to a nice, round 12 kilobyte. And that is really when we use every feature that the library has to offer. But this is not the typical starting point. So usually we can get quite far with just exporting a query client, the provider, and probably use query and use mutation. And if we do that, if we narrow it down, this gets us to under 10 kilobytes. That's 9.63.

So don't get me wrong. I think bundle size is an important thing to look at before adding a dependency. But the debate about what is lightweight and what isn't is not really the most important one when it comes to such a central piece, like your aging state manager, especially because there's one metric that is easily left out, and that is the bundle size you save by code you don't have to write. I think a library like RackQuery really pays for itself, because the more you use it, the more it saves you code that you don't have to write yourself.

So when checking the bundle size of a library, it's important to not think about the size that it adds immediately, but also about what it can save you in the long run. And on that scale, I think RackQuery is a clear win, because most custom solutions would probably be larger, or they might fail in some edge cases, because, yeah, caching and caching validation is really hard.

Okay, the next myth I want to look at is the fact that with RackQuery you can't even fetch on a button click. And I get that a lot, and the argument is that it's hard for RackQuery to do imperative data fetching. And it's true because RackQuery is declarative by default. What we do is we write the use query hook, and we pass a query key and a query function to it, and it runs automatically for us. Now this code would try to read the query from the cache, and if they don't exist, it will go and fetch them for us. So far, that looks good, but now let's try adding some filtering to our task list.

When we add a filter form, we run an apply callback, and when that gets called, we want to refetch that with those new filters. So if we explore what use query returns on our own, we might find the refetch function, and we might want to just pass a refetch function to it. I think this seems reasonable, but except that refetch doesn't take any argument, so this just doesn't work. And I get the frustration about this, but it's just not how RackQuery was designed to work. Because see, if we have a hardcoded key like tasks, and we'd refetch that with different arguments, we would not only override the data that we'd cached for those other filters, we would also run in race conditions with that effect.

So RackQuery has solved both of these problems with the declarative approach by putting all our dependencies, and that is everything that we use inside the query function, into the query key. And that means we have to store our applied filter somewhere, and in this example I've just put them into React state. Now when those applied filters change, the key changes and RackQuery will see a new query key and then it will fetch And this approach will get us from the imperative thinking, like if I click that button, I want to do some fetching, towards the declarative form of I want data that matches this state, and how it changes is actually irrelevant. And it's also relevant where we store those applied filters.

I've used useState before, but it's actually a pretty forward change to make a navigation with different search params if we use something like 10StackRouter. This is of course type safe, depending on the search param schema that we have defined on our route. And now we get a bunch of things for free, like for example shareable URLs or browser back button navigation, which I think is really cool. Another cool thing is that if we change the filters back to something that we've already searched, like I said before, we get an instant result. And that's because RackQuery caches everything separately by the key. In that sense it's a simple document cache where the complete responses will be stored for any given key. So yeah, in this example this also means that if a task is both in status open and in priority high, it will be in both of these caches. Because there is no normalized caching in RackQuery. In a normalized cache, every piece of data is stored only once, and other parts only reference it to avoid that data duplication.

There are dedicated solutions for GraphQL, for example, like Apollo Client or Urql, and they offer normalized caching because they are aware of the schema and the relations between entities. But RackQuery in this regard knows nothing, it doesn't know what is in the cache, it only knows the promise that gets returned. Now we have a long list of feature comparisons in our docs and normalized caching is pretty much the only thing that we don't support. It's a pretty hard problem to solve and it can also add a lot of complexity to your caching logic. So the trade-off that we've taken is to not support it. I also think that for most applications just refetching after an invalidation probably works fine and is also easier to reason about. So yeah, if you're using GraphQL and you need normalized caching, RackQuery might not be the best fit for you. There is however a community solution that I want to highlight which is called Normie. It tries to bring automatic normalization and data updates to data fetching libraries and it has integrations for RackQuery, SWR and RTKQuery. So you might want to check that out if that sounds interesting to you.

So we don't do normalized caching because we want to keep things simple but still one thing I hear a lot is that RackQuery is complicated and has a steep learning curve. Now I think if something is easy to understand that's always subjective. There could be something straightforward to understand for you that's a total mystery to me. But I think it's undeniable that RackQuery, like any concept that is worth applying, has a learning curve and it also has an API surface that isn't the smallest one. I went a lot into the details of RackQuery's API design in my last talk at the React Advanced Conference earlier this year. So if you want an in-depth look at that, please check that out. But just to touch on the topic I think Tana has a great tweet summarizing the design goals of RackQuery where he says that the query API is actually medium-sized when you unpack it all but the most important part is that you can understand and learn how to use it by starting with a single query that provides 80% of the entire value proposition first try. From there, the rest of its API can be gradually learned if needed. So while the query API might seem overwhelming at first, we don't need to learn everything at once. We can start just with useQuery with the minimal required options which is the query key and the query function. And we already get a ton of things from just using this simple code. We get caching and request duplication, there's stale while revalidate, background updates, global state management, retries, like the list goes on and on. And then later we might add a mutation to make some updates and then tie that back to the query with query invalidation. Now that's already a bit more code but with those two we can get really far in our application. And once our application complexity grows, we might want to look into some more deeper things that RackQuery has to offer. Maybe we want to add an optimistic update here and there in one of our places or maybe we need an infinite query sometimes. Now those are a bit more involved and then all the way up on this powerful and flexible scale we have our plug-in system and our very low level cache subscriptions that we are for example using to build our DevTools. Now those are really powerful and flexible but once you reach a certain application complexity, you might actually be probably happy that those exist as well. But I think the query API is absolutely designed to evolve with you. So yeah, don't believe that it's necessary to learn everything from the start, if that feels overwhelming.

Yes, there is a lot to learn but we can definitely get there incrementally. Okay. So once we have learned the API and we are thinking that it's actually pretty great, we want to start to manage all the state with it, right? But since ReqQuery is bad, it really doesn't want us to do that. It's really designed to work just with aging state only because it's an aging state manager that knows about the needs of the service state that we have and it's a good service state manager that knows about the needs of the service state that we are caching. It knows that the data we are seeing is only a snapshot of the source of truth from the time when we fetched it and that the actual source of truth lives on the server. So what it tries to do is it tries to revalidate and keeps our data up to date because it's also a data synchronization tool. And it might even make some assumptions about our network connection when it gets that state and it might actually retry getting that state too. These are all things that we love about ReqQuery but it's not something that we need when we want to manage some synchronous state like for example a sidebar toggle. If I were to write that code in ReqQuery this is probably what it would look like but don't do this. It's far from ideal. We need to do a bunch of things here. We need to come up with a unique key like sidebar state that doesn't collide with anything else that we have in our application. We don't even have a query function here because there's nothing asynchronous to do. We just pass data with initial data synchronously and then update it with set query data. And lastly we need to turn off a bunch of config options to actually stop ReqQuery from trying what it wants to do out of the box which is managing and synchronizing that asynchronous state. So I think doing something like this is not easy to get right. It's also a bit verbose and it's not very efficient either. So the split in client and service states that we have is really on purpose because they have different needs. So I would really use the right tool for the right job. And there are plenty of other solutions to manage client state. For example, one that I like is Zustand because it's minimal, efficient and unopinionated. All we have to do here is define a store with our state and then the actions to update it. And then I've created a custom hook just to keep the same interface that I had in the previous implementation. And something similar that I also quite like is XStateStore which looks pretty much the same but it works a bit better in TypeScript because the types are inferred and it's also event driven. But the thing here is there are no surprises with either one. They're both perfectly capable of managing that client state for us. So I think there are definitely better choices than just to use ReqQuery for everything. So the last point that I have is a bonus point. I think it's a bit funny that sometimes I hear the question like why do we even need a third-party library to do something as basic as data fetching in React? Why isn't this just built into React? And I can't really answer that because I don't work on React but I certainly get the frustration that we don't have something an agent primitive built into React like there is, for example, a create resource in SolidJS. But I think the reason for that could be that the React team really tries to get an API right before they actually ship it.

And as an example, I've often wondered, or I think lots of us have often wondered, why we don't have context selectors in React. That's something a lot of people have been requesting to get those fine-grained subscriptions to a React context. I think it's the reason why all those other state management libraries even exist is that this doesn't exist. We would have a settings context with a bunch of settings probably and then a theme on top of that and use-theme would only subscribe to that theme. And then on top of that, we would have use-color, which would only re-render the component that uses it when that specific color changes. Now, this doesn't exist and I think it's probably not because it would be too hard to implement but I think it's because the React team has a different vision. It's that we create a new use operator inside use-memo and then React will bail out of rendering if we return the same value. Now, I think this already composes a lot better than selectors and eventually, it might lead to a place where we can just write the same code without use-memo at all thanks to the React compiler. Now, I think that's a great vision but it takes time to get there so this is not real syntax, it doesn't exist. And of course, with data fetching, it was kind of like a similar story because everyone just wanted to have use-query but the React team just thinks bigger. I think suspense is a beautiful architecture where your components get decoupled from handling loading and error states and it also works really, really well with TypeScript because in this case, data can never be undefined. And of course, the React vision goes beyond client-side data fetching now that we have async server components. I really wish I had a quote from the React team but I couldn't find a good one so I'm just going to say it myself that suspense and server components are the async primitive that we've been waiting for. And yeah, if you're working with a framework that supports server components then please use them and until then, feel free to use query. Thank you. So thank you for the talk and there's a lot of love indeed in the community as you mentioned. I just want to read out one. There's a comment here. We use 10-sec query. I'm super happy with it. And if you don't, just read the documentation and try it out. So thank you for your work. But then there's this juiciest because essentially this person, I don't want to put words in their mouth but this is kind of like RTFM, read the manual type of comment. Or my blog. Or your blog. But there's another question here and there it is. Why are 10-sec docs so overwhelming? I think for juniors and newbies they can be very overwhelming. Now of course that's a hard balance to strike but do you have any thoughts about how you are doing and where is that right now? Yeah, that's a good point. I probably should have included that maybe in the talk. I think the docs are probably due to an overhaul.

The structure of the docs have been there since forever where we basically have like guides which I think is a good idea to start with guides and then basically the API definition and what you have and then the examples that we have. But I think the guides could be a bit more structured and should take you from like zero to the end in like one flow. I don't want to do advertising but I have a course where I do exactly that. So yeah, you can also get that if you want. I think it's good to advertise things that actually help people. If you're struggling with the docs, then maybe that's a good thing to check out.

Okay, well let's go via the democratic order and see the most upvoted questions. So, is TensorStack Query a good choice for Next.js app router apps? So I think this is kind of implying all of the server action stuff and whatever. I have a blog post on that topic. It's called You Might Not Need React Query. And still like I said if you're using a mature framework that has server components and actions built in and this is enough for your use case then I wouldn't just bring in TensorQuery right from the start just because this is how we've always done it. Just evaluate the situation.

There are still tons of situations where you don't have a Greenfield app and you want to move to the app router and you already have it in place, right? Then it's a good way to just keep it and migrate incrementally. But also there are probably some highly interactive use cases where a refetch or a revalidation only on a route navigation isn't enough. So you'd want that updates to happen more frequently with all the automatic updates that we have. Or maybe you have infinite query with infinite scrolling, which I think is still pretty hard to get done with just server components. So it just depends on the use case. We definitely try to bring a good integration with server components and also with Next.js itself, where you can initiate fetching on the server and then stream the promise to the client where the cache will then actually pick it up. We try to do this also more automatically. This is a bit of an experimental phase that we are in now. But yeah, I think you can use it. I don't think you have to use it.

Yeah, it's really interesting. So actually I interviewed you at the React advanced stage just a couple of months ago and you mentioned that API and I realized that we weren't using it at work, so I just put it in afterwards. So you learn something when you come to these things. One thing I noticed is that you kind of interchangeably in the talk title and now you speak, you use React query and 10 stack query the names, and I think there might be some confusion around that. So what's going on with that? So it used to be React query up until version 3. There's a DMPM package React query that still gets a lot of downloads. So to get the download to actually combine those two, I did that with Chatchpg by the way, to just combine the stat numbers. And then we decided that we actually had an agnostic core, like the core is just in JavaScript and React is a separate adaptor on top of that. And people started to make a view adaptor and a svelte adaptor on their own, but just depending on React query and then you would get a different framework on top of that. So we decided to do the whole rebranding with version 4 and we're actually publishing each package separately. There's a 10 stack query core package that is just plain TypeScript. There's 10 stack solid query, there's 10 stack view query and then there's also 10 stack React query, the package. So the full name would be 10 stack React query but I don't think anybody actually says that. So I just keep calling it React query.

And if we're talking about the concept itself, then it's probably 10 stack query. If you build apps, are you like 10 stack maximalist? Do you use the 10 stack router for example? Or is the query library more your primary interest? So the router is really cool project. In the last app that we've built from scratch, we also chose the router. I'm also maintaining the router now, so a full disclosure. Yeah, so I think some of the concepts in the router are really unique, like how search params are treated as a state manager, how you have the type safety that flows everywhere, how you have suspense integration on all the routes. Could be a good talk as well. Yeah, I guess I'll see you at the developers maintainer panel and then I'll see you at the don't burn out panel afterwards. Oh yeah, I thought it's the same panel, like it has to be the same. No, it's two different... one is people who have already acknowledged they have a problem and the people who are still walking in the problem. Okay, so let's go again, in a democratic order.

Are there any recommended patterns for combining React query with HTTP caching for REST APIs using for example cache control headers? You can definitely do that and it's a different kind of caching layer. We have like this stale time setting that basically defines when data becomes stale and it feels like cache control headers kind of like do a similar thing but one of the good things is that if you're using cache control headers I would just keep the stale time to zero because even if a fetch then triggers too often from React query it would still just be caught by the browser cache and would be delivered from that cache directly. So at this point you can keep the defaults and it doesn't really matter and it's actually good to use the browser cache for that as well because those fetch requests would also work while you're offline. So once you have that cached in the browser cache even if you don't have it in our in-memory cache those requests would still work. So yeah, a combination of those is definitely something you can do.