December 27, 2021

The Redux team is working hard to create tools that are helpful in many real-life situations. For example, Redux Toolkit is a big step in simplifying how we write applications with Redux. Another helpful tool is the Redux Toolkit Query. Its primary sources of inspiration are the Apollo Client and React Query.

The code we usually write for fetching data is often very repetitive. RTK Query aims to do a lot of the work and make our code more consistent and concise. It comes with loading state handling and even cache management. On top of that, RTK Query generates React hooks ready to use. It offers excellent support for TypeScript because it is written in it.

In this article, we go through all the basic features of RTK Query while using TypeScript.

Here we use an official Redux Toolkit template with TypeScript. To get it, run npx create-react-app my-app --template redux-typescript.

Defining the basics of our API

To start using the RTK Query, we need to use the createApi function.

A few important things are happening above. First, we need to define the reducerPath property to tell the Redux Toolkit where we want to keep all of the data from the API in our store.

We also need to tell the RTK how to make our API requests by providing the baseQuery parameter. A common way is using the fetchBaseQuery function, a wrapper around the native Fetch API. Even though the above is the solution suggested by the official documentation, RTK aims not to enforce it. So, for example, we can write our base query function that uses axios.

In the property called endpoints, we specify a set of operations we want to perform with the API. We do that by using the builder object. When we aim to retrieve the data, we should use the builder.query function. When we want to alter the data on the server, we need to call the builder.mutation method.

Both builder.query and builder.mutation uses generic types. For example, in getPhotoById: builder.query<Photo, number> the Photo is the type of data in the response. When getting the photo, the number is the type of argument we want the user to pass. Since the getPhotos query does not require any arguments, we must explicitly pass void.

Defining the endpoints causes the React Toolkit to generate a set of hooks to interact with our API. We need to use TypeScript in version 4.1 or greater for the hooks to work correctly.

In our code snippet, we use the REACT_APP_API_URL environment variable. Therefore, we need to add it to our .env file for the url to be available.

.env

Attaching the RTK Query to the store

The createApi function creates a reducer and a middleware we need to attach to our existing Redux store.

If you want to know more about Redux Middleware, check out Redux middleware and how to use it with WebSockets

Above, the setupListeners is a thing worth noting. We can set the refetchOnFocus or the refetchOnReconnect flags to true when using a query. They tell RTK Query to refetch the data when the application window regains focus, or the network connection is reestablished. For it to work, we need to listen to events such as:

• visibilitychange,
• focus,
• online,
• offline.

When we look under the hood, we can see that the setupListeners function attaches callbacks to the above events. So as long as you don’t use the mentioned flags, you don’t need to use setupListeners.

Querying the data

The essential auto-generated hook related to queries is the useQuery. Using it automatically fetches the data.

The cache behavior

It is essential to understand that if we render the PhotoCard multiple times with the same photoId, the useGetPhotoByIdQuery hook returns the result from the cache. The above happens as long as 60 seconds didn’t yet pass until the last component stopped using the useGetPhotoByIdQuery hook with a given id.

60 seconds can be changed to another value using the keepUnusedDataFor property.

We can alter this behavior in a few ways. For example, we can use the pollingInterval property to allow the query to refresh automatically.

Above I’m using a numeric separator to make the number more readable.

We can also use the refetchOnMountOrArgChange flag to skip the cached result.

Instead of true we can also pass a number of seconds. In this case RTK refetches if enough time has passed.

RTK also gives us a way to manually request the latest data with the refetch function.

We can also use the refetchOnFocus and refetchOnReconnect flags as mentioned before in this article.

Updating the data with mutations

To update the data, we need to use mutations. To do that, we can use the most significant hook used for mutation, the useMutation hook.

The crucial thing is that mutating a post with a given id should modify the cache. One way to achieve that is with tags.

Automated cache invalidating with tags

RTK query creates a tag system to automatically refetch the data affected by mutations. Queries can provide tags, while mutations can invalidate them.

In our example above, we can see that the getPhotos provides just one tag: { type: 'Photos', id: 'LIST' }.

The getPhotoById query provides one tag per photo. For example, using useGetPhotoByIdQuery(1) causes the { type: 'Photos', id: 1 } tag to be created.

The updatePhoto mutation would invalidate two tags if the update were successful.

Using the above mutation invalidates the following tags:

• { type: 'Photos', id: 1 }
• { type: 'Photos', id: 'LIST' }

Because of that, running the above mutation causes three API requests:

• PATCH /photos/1,
• GET /photos/1,
• GET /photos.

Thanks to doing the above, the cache is refreshed for the getPhotos and the getPhotoById query.

Manual cache invalidating

Making additional API requests every time we change a single photo is not optimal. In RESTful APIs, PATCH and PUT requests often return the modified entity. We can use that to perform manual cache invalidation. To do that, we need to define an onQueryStarted function.

One way of doing the above is to perform an optimistic update. We assume that our API request will probably be successful, and we want to make the changes immediately. However, if our API request fails for some reason, we undo our changes.

The second approach we can implement is the pessimistic update. Here, we wait for the request to be completed before modifying the cache.

Splitting the code

When using React Toolkit Query, we are expected to use the createApi function just once. However, when our application uses a lot of different endpoints, defining them in one place can lead to a messy codebase. Fortunately, with RTK, we can split our endpoints into multiple additional files.

Please notice that we’re still defining the tagTypes array in the main API definition. An alternative to doing that is to use the enhanceEndpoints function.

Summary

We’ve gone through all of the features we need to start using React Toolkit Query in this article. This included defining the API with code splitting, performing queries, and altering the cache with mutations. RTK Query proves to be a great tool that we can use for data fetching and caching. We can even use the Redux DevTools extension to view our cached data through the developer tools. It does a lot of the job for us and makes a lot of sense especially if we already use Redux in our application.