Migrating to React Query 3

Previous versions of React Query were awesome and brought some amazing new features, more magic, and an overall better experience to the library. They also brought on massive adoption and likewise a lot of refining fire (issues/contributions) to the library and brought to light a few things that needed more polish to make the library even better. v3 contains that very polish.

• More scalable and testable cache configuration
• Better SSR support
• Data-lag (previously usePaginatedQuery) anywhere!
• Bi-directional Infinite Queries
• Query data selectors!
• Fully configure defaults for queries and/or mutations before use
• More granularity for optional rendering optimization
• New useQueries hook! (Variable-length parallel query execution)
• Query filter support for the useIsFetching() hook!
• Retry/offline/replay support for mutations
• Observe queries/mutations outside of React
• Use the React Query core logic anywhere you want!
• Bundled/Colocated Devtools via react-query/devtools
• Cache Persistence to web storage (experimental via react-query/persistQueryClient-experimental and react-query/createWebStoragePersistor-experimental)

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 types 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.

When creating a new QueryClient(), a QueryCache and MutationCache are automatically created for you if you don't supply them.

import { QueryClient } from 'react-query'

const queryClient = new QueryClient()

Default options for queries and mutations can now be specified in QueryClient:

Notice that it's now defaultOptions instead of defaultConfig

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // query options
    },
    mutations: {
      // mutation options
    },
  },
})

The QueryClientProvider component is now used to connect a QueryClient to your application:

import { QueryClient, QueryClientProvider } from 'react-query'

const queryClient = new QueryClient()

function App() {
  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
}

As previously noted with a deprecation, there is no longer a default QueryCache that is created or exported from the main package. You must create your own via new QueryClient() or new QueryCache() (which you can then pass to new QueryClient({ queryCache }) )

It's been a long time coming, but it's finally gone :)

The new QueryClient.prefetchQuery() function is async, but does not return the data from the query. If you require the data, use the new QueryClient.fetchQuery() function

// Prefetch a query:
await queryClient.prefetchQuery('posts', fetchPosts)

// Fetch a query:
try {
  const data = await queryClient.fetchQuery('posts', fetchPosts)
} catch (error) {
  // Error handling
}

Together, these provide the same experience as before, but with added control to choose which component trees you want to reset. For more information, see:

• QueryErrorResetBoundary
• useQueryErrorResetBoundary

QueryCache.find() should now be used to look up individual queries from a cache

QueryCache.findAll() should now be used to look up multiple queries from a cache

Notice that it's now a function instead of a property

It returns the provided queryClient for its component tree and shouldn't need much tweaking beyond a rename.

Inline functions are now the suggested way of passing parameters to your query functions:

// Old
useQuery(['post', id], (_key, id) => fetchPost(id))

// New
useQuery(['post', id], () => fetchPost(id))

If you still insist on not using inline functions, you can use the newly passed QueryFunctionContext:

useQuery(['post', id], (context) => fetchPost(context.queryKey[1]))

They were previously added as the last query key parameter in your query function, but this proved to be difficult for some patterns

// Old
useInfiniteQuery(['posts'], (_key, pageParam = 0) => fetchPosts(pageParam))

// New
useInfiniteQuery(['posts'], ({ pageParam = 0 }) => fetchPosts(pageParam))

The new keepPreviousData options is available for both useQuery and useInfiniteQuery and will have the same "lagging" effect on your data:

import { useQuery } from 'react-query'

function Page({ page }) {
  const { data } = useQuery(['page', page], fetchPage, {
    keepPreviousData: true,
  })
}

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

• options.getFetchMore has been renamed to options.getNextPageParam
• queryResult.canFetchMore has been renamed to queryResult.hasNextPage
• queryResult.fetchMore has been renamed to queryResult.fetchNextPage
• queryResult.isFetchingMore has been renamed to queryResult.isFetchingNextPage
• Added the options.getPreviousPageParam option
• Added the queryResult.hasPreviousPage property
• Added the queryResult.fetchPreviousPage property
• Added the queryResult.isFetchingPreviousPage
• The data of an infinite query is now an object containing the pages and the pageParams used to fetch the pages: { pages: [data, data, data], pageParams: [...]}

One direction:

const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
  useInfiniteQuery(
    'projects',
    ({ pageParam = 0 }) => fetchProjects(pageParam),
    {
      getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
    },
  )

Both directions:

const {
  data,
  fetchNextPage,
  fetchPreviousPage,
  hasNextPage,
  hasPreviousPage,
  isFetchingNextPage,
  isFetchingPreviousPage,
} = useInfiniteQuery(
  'projects',
  ({ pageParam = 0 }) => fetchProjects(pageParam),
  {
    getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
    getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,
  },
)

One direction reversed:

const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
  useInfiniteQuery(
    'projects',
    ({ pageParam = 0 }) => fetchProjects(pageParam),
    {
      select: (data) => ({
        pages: [...data.pages].reverse(),
        pageParams: [...data.pageParams].reverse(),
      }),
      getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
    },
  )

This allows for easier manipulation of the data and the page params, like, for example, removing the first page of data along with it's params:

queryClient.setQueryData(['projects'], (data) => ({
  pages: data.pages.slice(1),
  pageParams: data.pageParams.slice(1),
}))

Though the old way gave us warm fuzzy feelings of when we first discovered useState for the first time, they didn't last long. Now the mutation return is a single object.

// Old:
const [mutate, { status, reset }] = useMutation()

// New:
const { mutate, status, reset } = useMutation()

• The [mutate] variable has been changed to the mutation.mutate function
• Added the mutation.mutateAsync function

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:

const { mutate } = useMutation({ mutationFn: addTodo })

mutate('todo', {
  onSuccess: (data) => {
    console.log(data)
  },
  onError: (error) => {
    console.error(error)
  },
  onSettled: () => {
    console.log('settled')
  },
})

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

const { mutateAsync } = useMutation({ mutationFn: addTodo })

try {
  const data = await mutateAsync('todo')
  console.log(data)
} catch (error) {
  console.error(error)
} finally {
  console.log('settled')
}

// Old:
useQuery({
  queryKey: 'posts',
  queryFn: fetchPosts,
  config: { staleTime: Infinity },
})

// New:
useQuery({
  queryKey: 'posts',
  queryFn: fetchPosts,
  staleTime: Infinity,
})

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) and a handy error will be thrown if a non-boolean value is passed.

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.

Honestly, we were accruing way too many refetchOn____ options, so this should clean things up.

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.

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.

With these new 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:

import { useQuery } from 'react-query'

function User() {
  const { data } = useQuery(['user'], fetchUser, {
    notifyOnChangeProps: ['data', 'error'],
  })
  return <div>Username: {data.username}</div>
}

Prevent re-render when the isStale property changes:

import { useQuery } from 'react-query'

function User() {
  const { data } = useQuery(['user'], fetchUser, {
    notifyOnChangePropsExclusions: ['isStale'],
  })
  return <div>Username: {data.username}</div>
}

Although it was called clear, it really just removed the query from the cache. The name now matches the functionality.

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

import { setLogger } from 'react-query'

// Log with Sentry
setLogger({
  error: (error) => {
    Sentry.captureException(error)
  },
})

// Log with Winston
setLogger(winston.createLogger())

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

import { setConsole } from 'react-query'

setConsole({
  log: console.log,
  warn: console.warn,
  error: console.warn,
})

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

QueryStatus has been changed from an enum to a union type

So, if you were checking the status property of a query or mutation against a QueryStatus enum property you will have to check it now against the string literal the enum previously held for each property.

Therefore you have to change the enum properties to their equivalent string literal, like this:

• QueryStatus.Idle -> 'idle'
• QueryStatus.Loading -> 'loading'
• QueryStatus.Error -> 'error'
• QueryStatus.Success -> 'success'

Here is an example of the changes you would have to make:

- import { useQuery, QueryStatus } from 'react-query'; // [!code --]
+ import { useQuery } from 'react-query'; // [!code ++]

const { data, status } = useQuery(['post', id], () => fetchPost(id))

- if (status === QueryStatus.Loading) { // [!code --]
+ if (status === 'loading') { // [!code ++]
  ...
}

- if (status === QueryStatus.Error) { // [!code --]
+ if (status === 'error') { // [!code ++]
  ...
}

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

import { useQuery } from 'react-query'

function User() {
  const { data } = useQuery(['user'], fetchUser, {
    select: (user) => user.username,
  })
  return <div>Username: {data}</div>
}

Set the notifyOnChangeProps option to ['data', 'error'] to only re-render when the selected data changes.

Wish you could run useQuery in a loop? The rules of hooks say no, but with the new useQueries() hook, you can!

import { useQueries } from 'react-query'

function Overview() {
  const results = useQueries([
    { queryKey: ['post', 1], queryFn: fetchPost },
    { queryKey: ['post', 2], queryFn: fetchPost },
  ])
  return (
    <ul>
      {results.map(({ data }) => data && <li key={data.id}>{data.title})</li>)}
    </ul>
  )
}

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

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

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

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

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

const observer = new QueryObserver(queryClient, { queryKey: 'posts' })

const unsubscribe = observer.subscribe((result) => {
  console.log(result)
  unsubscribe()
})

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

const observer = new InfiniteQueryObserver(queryClient, {
  queryKey: 'posts',
  queryFn: fetchPosts,
  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
})

const unsubscribe = observer.subscribe((result) => {
  console.log(result)
  unsubscribe()
})

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

const observer = new QueriesObserver(queryClient, [
  { queryKey: ['post', 1], queryFn: fetchPost },
  { queryKey: ['post', 2], queryFn: fetchPost },
])

const unsubscribe = observer.subscribe((result) => {
  console.log(result)
  unsubscribe()
})

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

queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })

function Component() {
  const { data } = useQuery(['posts'])
}

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

queryClient.setMutationDefaults(['addPost'], { mutationFn: addPost })

function Component() {
  const { mutate } = useMutation({ mutationKey: ['addPost'] })
}

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({ queryKey: ['posts'] })

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 entry point to only import the core functionality:

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

The devtools are now included in the react-query package itself under the import react-query/devtools. Simply replace react-query-devtools imports with react-query/devtools