Let's Build React Query in 150 Lines of Code!

Hi, everybody. My name is Tannyor Lindsly, and I'm a co-founder and UI UX engineer at Nozzle, and I'm the creator of the TAN stack, where we're trying our best to build open source software for React and JavaScript.

Almost one year ago exactly, I gave a talk here at React Summit, where I broke down the differences between server state and client state and the challenges that come with trying to manage server state all on your own. In that same talk, I introduced a tool called React Query. It's a library I built with the hope of alleviating most of the data fetching challenges that we experience in our React applications.

And since that day a year ago, React Query has received over 1,200 commits from over 250 contributors. And it's been adopted by indie developers, startups, Fortune 500s, and a handful of teams from companies I'm not legally allowed to mention probably. And I also released React Query Essentials which is my official course for learning the library from top to bottom. And React Query has received a ton of coverage from external articles and tutorials and top notch training material like Epic React. It's even being used as a core feature for up and coming frameworks like Blitz.js. All this awesome growth and attention has helped React Query become one of the best data fetching libraries for React and I'm super grateful for all of its usage and support it's received so far. So thank you so much.

By now, some of you are probably asking, what is React Query? So for those of you who aren't familiar with the overall concepts of the library, you're going to want to go back and listen to some of my previous talks and read the documentation to get familiar. But just so we're all on the same page today, I'll give you a quick two minute recap of what React Query is and what it can do.

Simply put, React Query is a data synchronization library. It coordinates fetching, caching, and updating data in your application. The data it handles can come from just about anywhere as long as that returns a promise. It builds upon the stale while revalidate concept, which means it provides cached data as often as possible while updating that data in the background as often as it makes sense for the components that consume it. So you provide the fetching logic and it takes care of everything else automatically. You can place React Query queries anywhere in your React application at any depth, and never have to worry about making duplicate network requests or managing global state or using context.

You can configure React Query to do other cool things like interval polling, prefetching, SSR, pagination, there's a lot of neat things that React Query can do. One of my favorites is that it has dedicated DevTools. There is a lot I could say about React Query right now. We could spend hours talking about the cool things it can do and that's actually what I do in my React Query Essentials course. So instead of doing that again and doing yet another talk on how to use React Query, I thought it would be fun today to do something different and show you how we could build our own version of React Query, or at least a miniature version. We'll call it React Query Lite. And by doing so, hopefully we can gain a better understanding of how it conceptually works under the hood.

To do this, we are going to build a Query Client, a Query Client Provider, and a Use Query hook. And that Use Query hook is going to have autofetching, autocaching, garbage collection, and we'll be able to configure stale time and cache time as well. And the big hope here... I'm hoping... that we'll be able to do it in under 150 lines of code. So we'll do our best. We'll see what happens. There is a warning here. I want to tell you that the code we're about to write is very untested. It's not type-safe. It's definitely naive and full of edge cases. You should not use this in production. Or development for that matter. So, just for learning purposes. It's going to be a lot of fun.

So let's get to it. to an app that I've built. And if you've used any of the React Query examples, this should look pretty familiar. It's an application that fetches a list of posts. In this case, five. We can click on them and it will load an individual post with a title and the body of the post. We can hit the back button. And you can see React Query's already doing its thing right here. We're using the normal React Query, where if we've loaded a post or a list of posts, then it just automatically loads the cached version. And then background fetches, if you hit it again, you can see that little green background fetching. So this is great. And React Query's doing its job. Let's go through the app really quick and show you what's happening.

We have a query client here that we're creating. We have the app component here that is basically just a router where we can set a post ID and see either the list of posts or a detailed view of a post. We've got our React Query DevTools here and everything's wrapped in our client provider.

Now we have our custom hooks that are using UseQuery. So here's our UsePosts hook which is calling UseQuery with the postKey and the query function to fetch some posts. We also have StaleTime and CacheTime which we will use later.

Here's the individual post, UsePosts hook, which takes a post ID, sets up the query key and the query function to fetch the individual post. And here's our display components, the Posts component where we are loading all of the posts, going through our loading and error states, and finally displaying our list of posts. And we also have our background fetching indicator right here. Down to our single Post view, we've got the post ID which we're passing into the UsePosts hook, our individual post query, and we're doing the same exact thing, just a loading and error state here, and finally showing the individual post along with another background updating indicator. And here's a little sleep function so that we can make the API that's really fast seem like it's a little bit slow, so we can see those loading indicators.

So our first step's going to be to kill off the actual React query and replace it with a new file, a blank file called ReactQueryLite. And obviously, everything's going to break, so let's head into our ReactQueryLite file and see what's going on.

We've got a query client provider, the query client, use query, and the DevTools. Right off the gate, we're probably not going to get to DevTools, so let's just return null on that and satisfy that requirement.

The next thing we're going to do is we're going to need to satisfy this query client provider that's giving us an error. So I'm going to take our little query client provider code and paste it in here, and what's going on here is we have the children that we're passing through. It takes the client, and then it's passing that client down to all the children. We're going to need a context to make this work, so let's create a context really quick. We have to create a context, and now we're getting an error because we're trying to read the property status of undefined in the use query hook. So let's just throw together kind of a dummy response from this use query hook that says everything's just loading all the time. No data, error undefined, is fetching true. So that kind of gets us to at least a working state where we're rendering something.

The next question we need to ask ourselves is what is a query exactly? Well, a query at the end of the day is probably just going to be an object, like a query object that's got some state on it with a fetch function. So why don't we make a new function down here called createQuery. It's going to share some of the signature from our useQuery hook, so the query key and the query function are going to get passed in here. We'll create the new query object and we'll set it up with some initial state. It's that same state that we're using right here. And we're going to have a setState function that lets us update our query state and a fetch function that lets us kick off the fetching for that. This is all just vanilla JavaScript right now. We'll get to hooking it up to React here in a minute.

So after we've done that, we need to kind of work with our state updater a little bit. So setState is going to take an updater function and basically just run that updater function with the existing state and return the new state, kind of like a reducer. Or if you've used setState before with React it's a lot like that.

Next up we have our fetch function, and our fetch function is going to be async for now. What this fetch function does is, the first thing we want to do is use our new setState function on the query to setIsFetching to true and clear out the error. Then we're going to, in a try-catch block, try and call our query function, so we'll use await here, get the data from the query function, and then if everything succeeds we're going to put status success and add our data. And then in our catch, if we have an error, we're going to do the same thing, just status error with the error. And finally, literally, finally, we're going to set queryPromise to null and query.setState we're going to setIsFetching to false.

So this quirky.promise doesn't exist yet, but we are going to need it. So let's set the promise to null up here, out of the gate. And what this is going to do is allow us to start setting up some de-duping. So if the query function is already being run or it's in progress, we don't want to fire it off again. We're going to use that query.promise property to do some promise magic. Instead of making this Fetch Function async here, we're going to wrap it in some other logic. We're going to wrap it in this block right here. So if there's not a promise yet, we're going to assign that promise to a new promise coming from this asynchronous function. And we can just dump all of our existing logic into that function right there. So it says if there's no promise, then kick off a new Fetch Function and assign it to the promise. And so that any other times we call Fetch if there already is a promise, we are just going to return it right here. So if not promise, then we'll just say return query.promise. And that takes care of our de-duping problem, which is a pretty slick and easy way to do that. We want to make sure that in the finally, whenever it finishes, we set that query promise to null so that we can fire it off again.

We can't wire this create query function right up to our useQuery hook. We have to allow the queries to be shared by multiple instances of useQuery, so we're going to have to create some subscriber support for all of this, and we're gonna start doing that in our query, in our createQuery function here. I'm going to create a new method on here called subscribe. It's going to take a subscriber, which is just an object for now, and we're gonna push that onto query.subscribers, so I'm going to need subscribers up here is going to be an array. And then it's going to return an unsubscribe function, which will just remove that from the subscriber list when we call it. And we also need to update our setState function right up here so that whenever we call setState we notify all the subscribers. We loop through them and we call subscriber.notify. And I'm just gonna move this down here, so we keep things organized.

And now our createQuery function is looking pretty good, but we are missing another vital piece. We need to have a place to store these queries once we create them. And that's where the query client comes into play. So if we come up here to the query client, this is just a class and we can make this really basic. We can just set up a constructor so that when we call newQueryClient we set this.queries to an empty array. This is just gonna be an array for all of our queries. And we'll set up a new class method here called getQuery. And getQuery is either going to get an existing query in that list or just create one and add it to it and then return it. So it's either creating or getting whatever we ask it to build for us. To do that we're going to hash the query key that we're getting from the options up here and we're just gonna use json.stringify to do that, to get a query hash. Once we have that hash, we can try and find an existing query just by looping over them and comparing the hashes. If we don't have a query already in here we're going to run our createQuery function with the options which is just the query key, the query function, all that stuff. But we gotta pass it the query client, too, that we're creating it with. So let's go down to createQuery and let's just add in the client here really quick so that signature matches up. And then we push that query into this.queries for the query client and then return it. So regardless, we're always returning a query here. So we're either creating it or grabbing an existing one.

So the next thing we need to do is make sure that our createQuery function supports our query key and query hash stuff. So let's make it so that the query key gets stored on there and the query hash is just always hashed inside of there so we can identify the query.

So from this point, we're still one step away from wiring up our queries to our useQuery hook. We still need one more thing in the middle to kind of coordinate all of the subscription stuff and make sure that we can use our queries multiple times throughout the app and really only have it create one query. So the way we're going to do that is with something called a query observer. I have a new function here called createQuery observer which is very similar to the one above. It takes a client and some of the query information and it's going to create an observer for us. It's also going to create a query right here if it needs to.

So we're going to call createQuery observer. It's going to either get or create the query and then it's going to create a new observer object. And this observer object has a couple of methods on it that we're going to go over. The first one is notify which for now is just empty but we're going to assign that to something here in a second. Next one is getResult which is just going to give us the queries state that this observer is observing when we call it. And the third one is subscribe. This is the one we're going to call from our usedQuery hook. So we're going to pass that a callback which is most likely going to be a render function to re-render our component when something changes. We're just going to take that callback and assign it to our observer.notify property. And then we're going to subscribe to the query itself with this observer that we are just creating here. And then we're going to get the unsubscribe function and return it. And then the most important part to enable our automatic fetching is this query.fetch here. Any time that we subscribe to a new observer we want to make sure that it's kicking off a fetch. So we're just going to call the query.fetch right here. And that will get deduped under the hood as well. So finally with all of this logic we can start hooking up our useQuery function. So let's go back up to useQuery and see how all of this comes together. Clearly we're not going to be sending back dummy data but instead we're going to be doing a bunch of things with the observer that we can create inside of here. The first section of this right here is we need to know what client we're dealing with. And we get that from the context that we are using up here passing down through our context provider. And we're going to pick it back up right here with react.useContext. So there's the client.

This next block here is just a very simple way to rerender a component that a hook is being used in. So just a little re-render function that we can force the component to re-render. The next part is the observer logic. So we want to store this observer on this ref and we only want to create one observer per instance of useQuery. So if it doesn't exist, we're going to create a query observer. We'll pass it the client we got from context. We'll pass the query key in query function we are getting from our useQuery options. And then we're going to store that on the observer ref.

From there, we're going to return the getResult function from our observer. If you remember, it returns the query state. So that's going to return the query state for whatever the observer is hooked up to. And then we set off an effect here, whenever this mounts, so that we can subscribe to that observer. And whenever something changes on the observer, we're going to re-render our component that useQuery is being used in. So, technically, this should all just work right now. Let's check our lines of code. We're at 130, and that's great. If we come over here, things should be loading, and you can see that it's working just great. If we reload the page, we get that hard loading state, but only for the first times that we're hitting things. And you can see we got that background refetching that's happening real nice. So this works great already, but we still have a few more things we need to do.

The next thing we need to do is add stale time. We need to come up to our use query function right here, and we're just going to add in stale time. And stale time really needs to be passed through down, down through our create query observer right here. So we'll go to our create query observer, and we'll pick it up right here. And stale time is just going to default to zero, so let's default it to zero right here. Then what we need to do is kind of shuffle some of this logic around. When we subscribe to a, an observer, instead of calling query.fetch, we want to do some checks first. Instead of doing query.fetch, I'm going to call something called observer.fetch, and we'll just create a new function right here on our observer. And this fetch is going to have some conditional logic inside of here, where we are going to be checking the last updated timestamp from the query. And we're going to take the date from now, or the time now, minus our last updated timestamp, and if that's greater than our stale time that we've defined, we're going to kick off the query.fetch. And for that to all work, we need to go up to where we are setting success for our query and make sure that we add that timestamp, last updated. So with that said, we should come back to our app, and let's turn on stale time for both of these and just see what happens. If we navigate around, we shouldn't be getting a background updating until three seconds has passed. And you can see that if I navigate back, we don't see it right there, but we will see it after the three seconds has elapsed. So stale time is working, and that's awesome.

The next thing we're going to do is, let's see, our lines of code are at a 142, so we are so, oh, that's React Querylight, 140. So we're getting pretty close, but we can still add a few more things.

Last thing we're going to do is cache time. So cache time is also going to be routed through use query. We're going to do cache time right here. And same thing, we're going to pass that through our observer creation, and we're going to pick it up right here, but cache time needs to be routed through a little bit further. So we're going to pass the cache time through to the get query function here. Get query gets passed up into here, options get thrown down into the create query function, and this is where we pick it up. And we're going to default that to five minutes just because that's what it is in React Query. So that's kind of fun. And this cache time is a little bit more involved, but it's pretty fun.

What we need to do is make sure that when the last subscriber is removed from a query that we check it and we say if there are no more subscribers, we're going to schedule a garbage collection on this query. So let's add that schedule GC function. We'll just add it right here. We're going to set a timeout that lasts for the cache time. So when the cache time runs out, we're going to remove this query from our query client and garbage collect it. We're going to need that garbage collection timeout variable as well. So let's add that up here and we'll just set it to null. And we also need a way to undo this as well. So let's do an unschedule GC garbage collection and that's just going to clear that timeout if it gets called, and we want to clear that if the, anytime the query gets subscribed to. So we'll just do that right here. Anytime we open up a new subscription to a query we want to make sure that it's not going to get garbage collected anymore. And that honestly should be everything we need. So if we come back in here and add in our cache time of five seconds, what's going to happen is if we wait for five seconds before we load this post, that main post list again, you're going to see a hard loading state right here. And that's because the query had already been garbage collected from the list after five seconds.

Those are all the base, those are all the base features that we talked about. And I think we have time for two more that I won't explain too much, but we'll just pop them in there. We'll come up here to the query client provider and just pop in this logic right here. And now, all of a sudden, we have refetching when we refocused the window. So we don't have to be navigating around.

We can come back and take off our stale time and cache time, which will make this a little more evident. And every time that we focus the window, it's going to background update. And then also, we've got an awesome dev tools component here too. I'm just going to paste in the entire dev tools component. And I know we're running short on time, but this is going to be fun. So let's find the dev tools. Let's just put it down at the bottom. Really simple dev tools, but it does rely on a few things. And we just need to add those really quick.

The dev tools need a way to subscribe to the query client itself. So we'll come up to the query client, add this.subscribers. We'll add a subscribe method to this class that's very similar to what we did with the query. And then we'll also add a notify method here as well, so that we can call notify and notify every single subscriber that it needs to rerun. So with that said, I think we just need to export our react query dev tools. And you know what, I'm just going to bring up the bottom of the window. So we can see it better. And there's our dev tools. So we need to also make sure that it's notifying, let's see we got set state right here. We need to make sure that we're also notifying the client when we set state or else the dev tools aren't going to update. And we should probably notify the client on garbage collection as well. So let's do it right there. There we go. You can see our post says success, we move to the next one, we get a nice little indication of our query key and success and this one is inactive but if we go back it comes back into play. If we go over here and load a new one. So there's some dev tools.

I know we're out of time so let's flip back and kind of wrap things up here. I really appreciate listening to what I had to say today. I think React Query is a great tool and I'm super excited about what the future has in store for React Query. At the heart of React Query, there really is an awesome community of sponsors and contributors and users and people who have really helped make it what it is today and I'd just like to say thank you to all those people. Be sure to come talk to me some more in chat.

I'm always open for a good chat. You can find me tanstack.com, nozel.io, and my handle is tannerlindsley just about everywhere else. So, thanks. Awesome, that was such a cool talk. Thank you so much, Tanner.

Let's discuss some of the poll results. So, Tanner wanted to know if you have used React Query before and 68% said they haven't tried yet, but 25% are using it now and 7% used it before. We've got some experienced React Query people in the audience. We got some amazing questions from the people in the Discord. That was a super fun talk by the way. Super impressed by your live coding skills. The gremlins always come out whenever I do live demos, so it's always impressive to see people writing code live and it actually working. It's a lot easier when you're just pasting things in. That's the trick. Copy and paste driven development is real. If I would have gone letter by letter, we wouldn't have gotten done in time. Awesome.

Okay. So let's run through these questions from the audience. So Aprilian asks, is V3 API going to stay stable for at least a few more months or should I wait for V4 before I migrate existing projects between major versions? It's definitely stable. It's going to stay that way for a while. You should upgrade now. But if we do release a V4, it's not going to be big breaking changes like it was with V3. It'll be little ones. We're taking it easy from here on out. So don't worry. Cool. So, that's a pretty definitive answer. Use V3. This username is tricky.

ALBSKJORR asks, when will React Native developer tools for ReactQuery be released? I don't know. I'm not working on them. I can't use React Native right now. So I hope that answers your question. Me neither. You should build them. Whoever asked that question, you should try to build them. That would be great. That would be really cool. Yeah, I've never done anything mobile dev, which I probably should at some point. Even React Native and Flutter I haven't tried.

Jordie VD asks, would ReactQuery have benefits over something like Apollo when using GraphQL? I've heard people say that ReactQuery is easier to understand and manipulate. Its API is a little bit more simple, but it doesn't have the first class GraphQL experience like you'd get with Apollo or ... So you wouldn't get the first class experience you would with Apollo or Urql. Cool.

We have time for one more question and then anybody who has a remaining question, Tara will be in the Spatial chat in order to answer more. So if you want to join in there, you can get your question asked, even if we don't get to it here. And the last question is, what's the suggested way to test components using UseQuery by MHI? React Testing Library. Test it like you would use it in your app. You can look at the React query tests themselves. We use React Testing Library and we don't test any implementation details. So do it like that. There you go, awesome, awesome. Another one that I'll do really quick because it's a yes or no, would you post the code for this? Yes. I will do my best to post the code on my GitHub. Awesome. Cool. But you heard in the presentation to not use this code. It's not production ready. Yeah, do not use this code. If I post it, do not use it and please don't ask me if it's concurrent-mode safe or suspense ready. Awesome, awesome. Cool.