Migrating to React Query 3

V3 migration

This article explains how to migrate your application to React Query 3.

QueryClient

The QueryCache has been split into a QueryClient and a QueryCache. The QueryCache contains all cached queries and the QueryClient can be used to interact with a cache.

This has some benefits:

• Allows for different type of caches.
• Multiple clients with different configurations can use the same cache.
• Clients can be used to track queries, which can be used for shared caches on SSR.
• The client API is more focused towards general usage.
• Easier to test the individual components.

Use the QueryClientProvider component to connect a QueryClient to your application:

1 import { QueryClient, QueryClientProvider, QueryCache } from 'react-query'
2 
3 const cache = new QueryCache()
4 const client = new QueryClient({ cache })
5 
6 function App() {
7   return <QueryClientProvider client={client}>...</QueryClientProvider>
8 }

useQueryCache()

The useQueryCache() hook has been replaced by the useQueryClient() hook:

1 import { useCallback } from 'react'
2 import { useQueryClient } from 'react-query'
3 
4 function Todo() {
5   const client = useQueryClient()
6 
7   const onClickButton = useCallback(() => {
8     client.invalidateQueries('posts')
9   }, [client])
10 
11   return <button onClick={onClickButton}>Refetch</button>
12 }

ReactQueryConfigProvider

The ReactQueryConfigProvider component has been removed. Default options for queries and mutations can now be specified in QueryClient:

1 const client = new QueryClient({
2   cache,
3   defaultOptions: {
4     queries: {
5       staleTime: Infinity,
6     },
7   },
8 })

usePaginatedQuery()

The usePaginatedQuery() hook has been replaced by the keepPreviousData option on useQuery:

1 import { useQuery } from 'react-query'
2 
3 function Page({ page }) {
4   const { data } = useQuery(['page', page], fetchPage, {
5     keepPreviousData: true,
6   })
7 }

Query object syntax

The object syntax has been collapsed:

1 // Old:
2 useQuery({
3   queryKey: 'posts',
4   queryFn: fetchPosts,
5   config: { staleTime: Infinity },
6 })
7 
8 // New:
9 useQuery({
10   queryKey: 'posts',
11   queryFn: fetchPosts,
12   staleTime: Infinity,
13 })

queryCache.prefetchQuery()

The client.prefetchQuery() method should now only be used for prefetching scenarios where the result is not relevant.

Use the client.fetchQueryData() method to get the query data or error:

1 // Prefetch a query:
2 await client.prefetchQuery('posts', fetchPosts)
3 
4 // Fetch a query:
5 try {
6   const data = await client.fetchQueryData('posts', fetchPosts)
7 } catch (error) {
8   // Error handling
9 }

ReactQueryCacheProvider

The ReactQueryCacheProvider component has been replaced by the QueryClientProvider component.

makeQueryCache()

The makeQueryCache() function has replaced by new QueryCache().

ReactQueryErrorResetBoundary

The ReactQueryErrorResetBoundary component has been renamed to QueryErrorResetBoundary.

queryCache.resetErrorBoundaries()

The queryCache.resetErrorBoundaries() method has been replaced by the QueryErrorResetBoundary component.

queryCache.getQuery()

The queryCache.getQuery() method has been replaced by cache.find().

queryCache.getQueries()

The queryCache.getQueries() method has been replaced by cache.findAll().

queryCache.isFetching

The queryCache.isFetching property has been replaced by client.isFetching().

QueryOptions.enabled

The enabled query option will now only disable a query when the value is false. If needed, values can be casted with !!userId or Boolean(userId).

QueryOptions.initialStale

The initialStale query option has been removed and initial data is now treated as regular data. Which means that if initialData is provided, the query will refetch on mount by default. If you do not want to refetch immediately, you can define a staleTime.

QueryOptions.forceFetchOnMount

The forceFetchOnMount query option has been replaced by refetchOnMount: 'always'.

QueryOptions.refetchOnMount

When refetchOnMount was set to false any additional components were prevented from refetching on mount. In version 3 only the component where the option has been set will not refetch on mount.

QueryResult.clear()

The QueryResult.clear() method has been renamed to QueryResult.remove().

setConsole

The setConsole function has been replaced by setLogger:

1 import { setLogger } from 'react-query'
2 
3 // Log with Sentry
4 setLogger({
5   error: error => {
6     Sentry.captureException(error)
7   },
8 })
9 
10 // Log with Winston
11 setLogger(winston.createLogger())

To prevent showing error screens in React Native when a query fails it was necessary to manually change the Console:

1 import { setConsole } from 'react-query'
2 
3 setConsole({
4   log: console.log,
5   warn: console.warn,
6   error: console.warn,
7 })

In version 3 this is done automatically when React Query is used in React Native.

New features

Some new features have also been added besides the API changes, performance improvements and file size reduction.

Selectors

The useQuery and useInfiniteQuery hooks now have a select option to select or transform parts of the query result.

1 import { useQuery } from 'react-query'
2 
3 function User() {
4   const { data } = useQuery('user', fetchUser, {
5     select: user => user.username,
6   })
7   return <div>Username: {data}</div>
8 }

Set the notifyOnStatusChange option to false to only re-render when the selected data changes.

useQueries()

The useQueries() hook can be used to fetch a variable number of queries:

1 import { useQueries } from 'react-query'
2 
3 function Overview() {
4   const results = useQueries([
5     { queryKey: ['post', 1], queryFn: fetchPost },
6     { queryKey: ['post', 2], queryFn: fetchPost },
7   ])
8   return (
9     <ul>
10       {results.map(({ data }) => data && <li key={data.id}>{data.title})</li>)}
11     </ul>
12   )
13 }

client.watchQuery()

The client.watchQuery() method can be used to create and/or watch a query:

1 const observer = client.watchQuery('posts')
2 
3 const unsubscribe = observer.subscribe(result => {
4   console.log(result)
5   unsubscribe()
6 })

client.watchQueries()

The client.watchQueries() method can be used to create and/or watch multiple queries:

1 const observer = client.watchQueries([
2   { queryKey: ['post', 1], queryFn: fetchPost },
3   { queryKey: ['post', 2], queryFn: fetchPost },
4 ])
5 
6 const unsubscribe = observer.subscribe(result => {
7   console.log(result)
8   unsubscribe()
9 })

client.setQueryDefaults

The client.setQueryDefaults() method to set default options for a specific query. If the query does not exist yet it will create it.

1 client.setQueryDefaults('posts', fetchPosts)
2 
3 function Component() {
4   const { data } = useQuery('posts')
5 }

useIsFetching()

The useIsFetching() hook now accepts filters which can be used to for example only show a spinner for certain type of queries:

 const fetches = useIsFetching(['posts'])

Core separation

The core of React Query is now fully separated from React, which means it can also be used standalone or in other frameworks. Use the react-query/core entrypoint to only import the core functionality:

 import { QueryClient } from 'react-query/core'