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, QueryCache and MutationCache. The QueryCache contains all queries, the MutationCache contains all mutations, and the QueryClient can be used to set configuration and to interact with them.

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:

NOTE There is no longer a default query cache, you must connect your application to a query provider manually

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

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 queryClient = useQueryClient()
6 
7   const onClickButton = useCallback(() => {
8     queryClient.invalidateQueries('posts')
9   }, [queryClient])
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 queryClient = new QueryClient({
2   defaultOptions: {
3     queries: {
4       staleTime: Infinity,
5     },
6   },
7 })

Query function parameters

Query functions now get a QueryFunctionContext instead of the query key parameters.

The QueryFunctionContext contains a queryKey and a pageParam in case of ininite queries.

useQuery:

1 // Old
2 useQuery(['post', id], (_key, id) => fetchPost(id))
3 
4 // New
5 useQuery(['post', id], () => fetchPost(id))

useInfiniteQuery:

1 // Old
2 useInfiniteQuery(['posts'], (_key, pageParam = 0) => fetchPosts(pageParam))
3 
4 // New
5 useInfiniteQuery(['posts'], ({ pageParam = 0 }) => fetchPost(pageParam))

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 }

useInfiniteQuery()

The useInfiniteQuery() interface has changed to fully support bi-directional infinite lists and manual updates.

The data of an infinite query is now an object containing the pages and the pageParams used to fetch the pages.

One direction:

1 const {
2   data,
3   fetchNextPage,
4   hasNextPage,
5   isFetchingNextPage,
6 } = useInfiniteQuery(
7   'projects',
8   ({ pageParam = 0 }) => fetchProjects(pageParam),
9   {
10     getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
11   }
12 )

Both directions:

1 const {
2   data,
3   fetchNextPage,
4   fetchPreviousPage,
5   hasNextPage,
6   hasPreviousPage,
7   isFetchingNextPage,
8   isFetchingPreviousPage,
9 } = useInfiniteQuery(
10   'projects',
11   ({ pageParam = 0 }) => fetchProjects(pageParam),
12   {
13     getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
14     getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,
15   }
16 )

One direction reversed:

1 const {
2   data,
3   fetchNextPage,
4   hasNextPage,
5   isFetchingNextPage,
6 } = useInfiniteQuery(
7   'projects',
8   ({ pageParam = 0 }) => fetchProjects(pageParam),
9   {
10     select: data => ({
11       pages: [...data.pages].reverse(),
12       pageParams: [...data.pageParams].reverse(),
13     }),
14     getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
15   }
16 )

Manually removing the first page:

1 queryClient.setQueryData('projects', data => ({
2   pages: data.pages.slice(1),
3   pageParams: data.pageParams.slice(1),
4 }))

useMutation()

The useMutation() hook now returns an object instead of an array:

1 // Old:
2 const [mutate, { status, reset }] = useMutation()
3 
4 // New:
5 const { mutate, status, reset } = useMutation()

Previously the mutate function returned a promise which resolved to undefined if a mutation failed instead of throwing. We got a lot of questions regarding this behavior as users expected the promise to behave like a regular promise. Because of this the mutate function is now split into a mutate and mutateAsync function.

The mutate function can be used when using callbacks:

1 const { mutate } = useMutation(addTodo)
2 
3 mutate('todo', {
4   onSuccess: data => {
5     console.log(data)
6   },
7   onError: error => {
8     console.error(error)
9   },
10   onSettled: () => {
11     console.log('settled)
12   },
13 })

The mutateAsync function can be used when using async/await:

1 const { mutateAsync } = useMutation(addTodo)
2 
3 try {
4   const data = await mutateAsync('todo')
5   console.log(data)
6 } catch (error) {
7   console.error(error)
8 } finally {
9   console.log('settled)
10 }

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 queryClient.prefetchQuery() method should now only be used for prefetching scenarios where the result is not relevant.

Use the queryClient.fetchQuery() method to get the query data or error:

1 // Prefetch a query:
2 await queryClient.prefetchQuery('posts', fetchPosts)
3 
4 // Fetch a query:
5 try {
6   const data = await queryClient.fetchQuery('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 queryCache.find().

queryCache.getQueries()

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

queryCache.isFetching

The queryCache.isFetching property has been replaced by queryClient.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.

QueryOptions.queryFnParamsFilter

The queryFnParamsFilter option has been removed because query functions now get a QueryFunctionContext object instead of the query key.

Parameters can still be filtered within the query function itself as the QueryFunctionContext also contains the query key.

QueryOptions.notifyOnStatusChange

The notifyOnStatusChange option has been replaced by the notifyOnChangeProps and notifyOnChangePropsExclusions props.

With these options it is possible to configure when a component should re-render on a granular level.

Only re-render when the data or error properties change:

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

Prevent re-render when the isStale property changes:

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

QueryResult.clear()

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

QueryResult.updatedAt

Because data and errors can be present at the same time, the updatedAt property has been split into dataUpdatedAt and errorUpdatedAt.

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 notifyOnChangeProps option to ['data', 'error'] 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 }

Retry/offline mutations

By default React Query will not retry a mutation on error, but it is possible with the retry option:

1 const mutation = useMutation(addTodo, {
2   retry: 3,
3 })

If mutations fail because the device is offline, they will be retried in the same order when the device reconnects.

Persist mutations

Mutations can now be persisted to storage and resumed at a later point. More information can be found in the mutations documentation.

QueryObserver

A QueryObserver can be used to create and/or watch a query:

1 const observer = new QueryObserver(queryClient, { queryKey: 'posts' })
2 
3 const unsubscribe = observer.subscribe(result => {
4   console.log(result)
5   unsubscribe()
6 })

InfiniteQueryObserver

A InfiniteQueryObserver can be used to create and/or watch an infinite query:

1 const observer = new InfiniteQueryObserver(queryClient, {
2   queryKey: 'posts',
3   queryFn: fetchPosts,
4   getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
5   getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
6 })
7 
8 const unsubscribe = observer.subscribe(result => {
9   console.log(result)
10   unsubscribe()
11 })

QueriesObserver

A QueriesObserver can be used to create and/or watch multiple queries:

1 const observer = new QueriesObserver(queryClient, [
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 })

Set default options for specific queries

The queryClient.setQueryDefaults() method can be used to set default options for specific queries:

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

Set default options for specific mutations

The queryClient.setMutationDefaults() method can be used to set default options for specific mutations:

1 queryClient.setMutationDefaults('addPost', { mutationFn: addPost })
2 
3 function Component() {
4   const { mutate } = useMutation('addPost')
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'