Migrating to React Query 4

Breaking Changes

Query Keys (and Mutation Keys) need to be an Array

In v3, Query and Mutation Keys could be a String or an Array. Internally, React Query has always worked with Array Keys only, and we've sometimes exposed this to consumers. For example, in the queryFn, you would always get the key as an Array to make working with Default Query Functions easier.

However, we have not followed this concept through to all apis. For example, when using the predicate function on Query Filters you would get the raw Query Key. This makes it difficult to work with such functions if you use Query Keys that are mixed Arrays and Strings. The same was true when using global callbacks.

To streamline all apis, we've decided to make all keys Arrays only:

1 - useQuery('todos', fetchTodos)
2 + useQuery(['todos'], fetchTodos)

Separate hydration exports have been removed

With version 3.22.0, hydration utilities moved into the React Query core. With v3, you could still use the old exports from react-query/hydration, but these exports have been removed with v4.

1 - import { dehydrate, hydrate, useHydrate, Hydrate } from 'react-query/hydration'
2 + import { dehydrate, hydrate, useHydrate, Hydrate } from 'react-query'

notifyOnChangeProps property no longer accepts "tracked" as a value

The notifyOnChangeProps option no longer accepts a "tracked" value. Instead, useQuery defaults to tracking properties. All queries using notifyOnChangeProps: "tracked" should be updated by removing this option.

If you would like to bypass this in any queries to emulate the v3 default behavior of re-rendering whenever a query changes, notifyOnChangeProps now accepts an "all" value to opt-out of the default smart tracking optimization.

notifyOnChangePropsExclusion has been removed

In v4, notifyOnChangeProps defaults to the "tracked" behavior of v3 instead of undefined. Now that "tracked" is the default behavior for v4, it no longer makes sense to include this config option.

Consistent behavior for cancelRefetch

The cancelRefetch can be passed to all functions that imperatively fetch a query, namely:

• queryClient.refetchQueries
  • queryClient.invalidateQueries
  • queryClient.resetQueries
• refetch returned from useQuery
• fetchNetPage and fetchPreviousPage returned from useInfiniteQuery

Except for fetchNetxPage and fetchPreviousPage, this flag was defaulting to false, which was inconsistent and potentially troublesome: Calling refetchQueries or invalidateQueries after a mutation might not yield the latest result if a previous slow fetch was already ongoing, because this refetch would have been skipped.

We believe that if a query is actively refetched by some code you write, it should, per default, re-start the fetch.

That is why this flag now defaults to true for all methods mentioned above. It also means that if you call refetchQueries twice in a row, without awaiting it, it will now cancel the first fetch and re-start it with the second one:

1 queryClient.refetchQueries({ queryKey: ['todos'] })
2 // this will abort the previous refetch and start a new fetch
3 queryClient.refetchQueries({ queryKey: ['todos'] })

You can opt-out of this behaviour by explicitly passing cancelRefetch:false:

1 queryClient.refetchQueries({ queryKey: ['todos'] })
2 // this will not abort the previous refetch - it will just be ignored
3 queryClient.refetchQueries({ queryKey: ['todos'] }, { cancelRefetch: false })

Note: There is no change in behaviour for automatically triggered fetches, e.g. because a query mounts or because of a window focus refetch.

Query Filters

A query filter is an object with certain conditions to match a query. Historically, the filter options have mostly been a combination of boolean flags. However, combining those flags can lead to impossible states. Specifically:

1 active?: boolean
2   - When set to true it will match active queries.
3   - When set to false it will match inactive queries.
4 inactive?: boolean
5   - When set to true it will match inactive queries.
6   - When set to false it will match active queries.

Those flags don't work well when used together, because they are mutually exclusive. Setting false for both flags could match all queries, judging from the description, or no queries, which doesn't make much sense.

With v4, those filters have been combined into a single filter to better show the intent:

1 - active?: boolean
2 - inactive?: boolean
3 + type?: 'active' | 'inactive' | 'all'

The filter defaults to all, and you can choose to only match active or inactive queries.

refetchActive / refetchInactive

queryClient.invalidateQueries had two additional, similar flags:

1 refetchActive: Boolean
2   - Defaults to true
3   - When set to false, queries that match the refetch predicate and are actively being rendered via useQuery and friends will NOT be refetched in the background, and only marked as invalid.
4 refetchInactive: Boolean
5   - Defaults to false
6   - When set to true, queries that match the refetch predicate and are not being rendered via useQuery and friends will be both marked as invalid and also refetched in the background

For the same reason, those have also been combined:

1 - active?: boolean
2 - inactive?: boolean
3 + refetchType?: 'active' | 'inactive' | 'all' | 'none'

This flag defaults to active because refetchActive defaulted to true. This means we also need a way to tell invalidateQueries to not refetch at all, which is why a fourth option (none) is also allowed here.

Streamlined NotifyEvents

Subscribing manually to the QueryCache has always given you a QueryCacheNotifyEvent, but this was not true for the MutationCache. We have streamlined the behavior and also adapted event names accordingly.

QueryCacheNotifyEvent

1 - type: 'queryAdded'
2 + type: 'added'
3 - type: 'queryRemoved'
4 + type: 'removed'
5 - type: 'queryUpdated'
6 + type: 'updated'

MutationCacheNotifyEvent

The MutationCacheNotifyEvent uses the same types as the QueryCacheNotifyEvent.

Note: This is only relevant if you manually subscribe to the caches via queryCache.subscribe or mutationCache.subscribe

The src/react directory was renamed to src/reactjs

Previously, React Query had a directory named react which imported from the react module. This could cause problems with some Jest configurations, resulting in errors when running tests like:

 TypeError: Cannot read property 'createContext' of undefined

With the renamed directory this no longer is an issue.

If you were importing anything from 'react-query/react' directly in your project (as opposed to just 'react-query'), then you need to update your imports:

1 - import { QueryClientProvider } from 'react-query/react';
2 + import { QueryClientProvider } from 'react-query/reactjs';

onSuccess is no longer called from setQueryData

This was confusing to many and also created infinite loops if setQueryData was called from within onSuccess. It was also a frequent source of error when combined with staleTime, because if data was read from the cache only, onSuccess was not called.

Similar to onError and onSettled, the onSuccess callback is now tied to a request being made. No request -> no callback.

If you want to listen to changes of the data field, you can best do this with a useEffect, where data is part of the dependency Array. Since React Query ensures stable data through structural sharing, the effect will not execute with every background refetch, but only if something within data has changed:

1 const { data } = useQuery({ queryKey, queryFn })
2 React.useEffect(() => mySideEffectHere(data), [data])

persistQueryClient and the corresponding persister plugins are no longer experimental and have been renamed

The plugins createWebStoragePersistor and createAsyncStoragePersistor have been renamed to createWebStoragePersister and createAsyncStoragePersister respectively. The interface Persistor in persistQueryClient has also been renamed to Persister. Checkout this stackexchange for the motivation of this change.

Since these plugins are no longer experimental, their import paths have also been updated:

1 - import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
2 - import { createWebStoragePersistor } from 'react-query/createWebStoragePersistor-experimental'
3 - import { createAsyncStoragePersistor } from 'react-query/createAsyncStoragePersistor-experimental'
4 
5 + import { persistQueryClient } from 'react-query/persistQueryClient'
6 + import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
7 + import { createAsyncStoragePersister } from 'react-query/createAsyncStoragePersister'

The cancel method on promises is no longer supported

The old cancel method that allowed you to define a cancel function on promises, which was then used by the library to support query cancellation, has been removed. We recommend to use the newer API (introduced with v3.30.0) for query cancellation that uses the AbortController API internally and provides you with an AbortSignal instance for your query function to support query cancellation.

Queries and mutations, per default, need network connection to run

Please read the New Features announcement about online / offline support, and also the dedicated page about Network mode

Even though React Query is an Async State Manager that can be used for anything that produces a Promise, it is most often used for data fetching in combination with data fetching libraries. That is why, per default, queries and mutations will be paused if there is no network connection. If you want to opt-in to the previous behavior, you can globally set networkMode: offlineFirst for both queries and mutations:

1 new QueryClient({
2   defaultOptions: {
3     queries: {
4       networkMode: 'offlineFirst'
5     },
6     mutations: {
7       networkmode: 'offlineFirst'
8     }
9   }
10 })

Removed undocumented methods from the queryClient

The methods cancelMutatations and executeMutation were undocumented and unused internally, so we removed them. Since they were just wrappers around methods available on the mutationCache, you can still use the functionality.

1 - cancelMutations(): Promise<void> {
2 -   const promises = notifyManager.batch(() =>
3 -     this.mutationCache.getAll().map(mutation => mutation.cancel())
4 -   )
5 -   return Promise.all(promises).then(noop).catch(noop)
6 - }

1 - executeMutation<
2 -   TData = unknown,
3 -   TError = unknown,
4 -   TVariables = void,
5 -   TContext = unknown
6 - >(
7 -   options: MutationOptions<TData, TError, TVariables, TContext>
8 - ): Promise<TData> {
9 -   return this.mutationCache.build(this, options).execute()
10 - }

New Features 🚀

Proper offline support

In v3, React Query has always fired off queries and mutations, but then taken the assumption that if you want to retry it, you need to be connected to the internet. This has led to several confusing situations:

• You are offline and mount a query - it goes to loading state, the request fails, and it stays in loading state until you go online again, even though it is not really fetching.
• Similarly, if you are offline and have retries turned off, your query will just fire and fail, and the query goes to error state.
• You are offline and want to fire off a query that doesn't necessarily need network connection (because you can use React Query for something other than data fetching), but it fails for some other reason. That query will now be paused until you go online again.
• Window focus refetching didn't do anything at all if you were offline.

With v4, React Query introduces a new networkMode to tackle all these issues. Please read the dedicated page about the new Network mode for more information.

Mutation Cache Garbage Collection

Mutations can now also be garbage collected automatically, just like queries. The default cacheTime for mutations is also set to 5 minutes.

Tracked Queries per default

React Query defaults to "tracking" query properties, which should give you a nice boost in render optimization. The feature has existed since v3.6.0 and has now become the default behavior with v4.