Migrating to React Query v3

Complete migration guide for upgrading from v2 to v3 with breaking changes and new features

React Query v3 brings significant improvements, better SSR support, and many new features while refining the API based on community feedback.

Overview of Changes

Architecture

Scalable and testable cache configuration with separated QueryCache and MutationCache

SSR Support

Improved server-side rendering capabilities

Data Lag

Keep previous data visible while new data loads (replaces usePaginatedQuery)

Bi-directional

Infinite queries can now paginate in both directions

Selectors

Query data selectors for transformation and memoization

useQueries

New hook for variable-length parallel query execution

Breaking Changes

QueryCache Split into QueryClient and Caches

The QueryCache has been split into QueryClient, QueryCache, and MutationCache:

Before (v2)

import { QueryCache } from 'react-query'

const queryCache = new QueryCache()

queryCache.prefetchQuery('todos', fetchTodos)

import { QueryClient } from 'react-query'

const queryClient = new QueryClient()

queryClient.prefetchQuery('todos', fetchTodos)

Benefits:

• Different types of caches
• Multiple clients with different configurations can share the same cache
• Cleaner API focused on general usage
• Easier to test individual components

New QueryClientProvider

Before (v2)

import { ReactQueryCacheProvider, ReactQueryConfigProvider } from 'react-query'

const queryCache = new QueryCache()

function App() {
  return (
    <ReactQueryConfigProvider config={{ queries: { staleTime: 60000 } }}>
      <ReactQueryCacheProvider queryCache={queryCache}>
        <YourApp />
      </ReactQueryCacheProvider>
    </ReactQueryConfigProvider>
  )
}

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

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60000,
    },
  },
})

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

Note the change from defaultConfig to defaultOptions.

Default QueryCache Removed

Before (v2)

import { useQuery } from 'react-query'

// Uses default global cache
function Component() {
  const { data } = useQuery('todos', fetchTodos)
}

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

const queryClient = new QueryClient()

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

function Component() {
  const { data } = useQuery('todos', fetchTodos)
}

prefetchQuery Changed

Before (v2)

const data = await queryCache.prefetchQuery('todos', fetchTodos)

// prefetchQuery no longer returns data
await queryClient.prefetchQuery('todos', fetchTodos)

// Use fetchQuery to get data
const data = await queryClient.fetchQuery('todos', fetchTodos)

Error Boundaries

Before (v2)

import { ReactQueryErrorResetBoundary } from 'react-query'

<ReactQueryErrorResetBoundary>
  {({ reset }) => (
    <ErrorBoundary onReset={reset}>
      <App />
    </ErrorBoundary>
  )}
</ReactQueryErrorResetBoundary>

import { QueryErrorResetBoundary, useQueryErrorResetBoundary } from 'react-query'

<QueryErrorResetBoundary>
  {({ reset }) => (
    <ErrorBoundary onReset={reset}>
      <App />
    </ErrorBoundary>
  )}
</QueryErrorResetBoundary>

// Or use the hook
function Component() {
  const { reset } = useQueryErrorResetBoundary()
  
  return (
    <ErrorBoundary onReset={reset}>
      <App />
    </ErrorBoundary>
  )
}

Cache Methods Renamed

Before (v2)

queryCache.getQuery('todos')
queryCache.getQueries(['todos'])

queryCache.find(['todos'])
queryCache.findAll(['todos'])

isFetching is Now a Method

Before (v2)

const isFetching = queryCache.isFetching

const isFetching = queryClient.isFetching()

// Can also filter
const isFetchingTodos = queryClient.isFetching(['todos'])

useQueryCache → useQueryClient

Before (v2)

import { useQueryCache } from 'react-query'

const queryCache = useQueryCache()

import { useQueryClient } from 'react-query'

const queryClient = useQueryClient()

Query Functions No Longer Receive Split Parameters

Before (v2)

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

// Use inline function (recommended)
useQuery(['post', id], () => fetchPost(id))

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

Infinite Query Page Params

Before (v2)

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

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

usePaginatedQuery Removed

Use keepPreviousData option instead:

Before (v2)

import { usePaginatedQuery } from 'react-query'

const { data, resolvedData } = usePaginatedQuery(['page', page], fetchPage)

import { useQuery } from 'react-query'

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

Infinite Queries are Bi-directional

Before (v2)

const {
  data,
  fetchMore,
  canFetchMore,
  isFetchingMore,
} = useInfiniteQuery('projects', fetchProjects, {
  getFetchMore: (lastPage) => lastPage.nextCursor,
})

if (data) {
  return data.map((page) => page.data)
}

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

if (data) {
  return data.pages.map((page) => page.data)
}

Changes:

• getFetchMore → getNextPageParam
• canFetchMore → hasNextPage
• fetchMore → fetchNextPage
• isFetchingMore → isFetchingNextPage
• Added getPreviousPageParam, hasPreviousPage, fetchPreviousPage, isFetchingPreviousPage
• Data is now { pages: [...], pageParams: [...] }

useMutation Returns Object

Before (v2)

const [mutate, { status, reset }] = useMutation(addTodo)

const { mutate, status, reset } = useMutation(addTodo)

mutate No Longer Returns Promise

Before (v2)

const [mutate] = useMutation(addTodo)

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

const { mutate, mutateAsync } = useMutation(addTodo)

// Use callbacks
mutate('todo', {
  onSuccess: (data) => console.log(data),
  onError: (error) => console.error(error),
})

// Or use mutateAsync
try {
  const data = await mutateAsync('todo')
  console.log(data)
} catch (error) {
  console.error(error)
}

Query Options Collapsed

Before (v2)

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

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

enabled Must Be Boolean

Before (v2)

useQuery('user', fetchUser, {
  enabled: userId, // truthy/falsy
})

useQuery('user', fetchUser, {
  enabled: Boolean(userId), // must be boolean
})

initialStale Option Removed

Initial data now respects staleTime:

Before (v2)

useQuery('todos', fetchTodos, {
  initialData: cachedTodos,
  initialStale: true,
})

useQuery('todos', fetchTodos, {
  initialData: cachedTodos,
  staleTime: 0, // Refetch immediately
})

// Or don't refetch:
useQuery('todos', fetchTodos, {
  initialData: cachedTodos,
  staleTime: Infinity,
})

refetchOnMount Scoped to Component

Before (v2)

// refetchOnMount: false affected all observers
useQuery('todos', fetchTodos, { refetchOnMount: false })

// refetchOnMount: false only affects this component
useQuery('todos', fetchTodos, { refetchOnMount: false })

notifyOnStatusChange Replaced

Before (v2)

useQuery('todos', fetchTodos, {
  notifyOnStatusChange: false,
})

// Only re-render when specific properties change
useQuery('todos', fetchTodos, {
  notifyOnChangeProps: ['data', 'error'],
})

// Or exclude specific properties
useQuery('todos', fetchTodos, {
  notifyOnChangePropsExclusions: ['isStale'],
})

clear() Renamed to remove()

Before (v2)

const query = useQuery('todos', fetchTodos)
query.clear()

const query = useQuery('todos', fetchTodos)
query.remove()

updatedAt Split

Before (v2)

const { updatedAt } = useQuery('todos', fetchTodos)

const { dataUpdatedAt, errorUpdatedAt } = useQuery('todos', fetchTodos)

setConsole() Replaced

Before (v2)

import { setConsole } from 'react-query'

setConsole({ log, warn, error })

import { setLogger } from 'react-query'

setLogger({ log, warn, error })

// Works with Winston, Sentry, etc.

React Native Auto-Configuration

React Native error logging is now automatic (no need to override console).

TypeScript: QueryStatus is Union Type

Before (v2)

import { useQuery, QueryStatus } from 'react-query'

const { status } = useQuery('todos', fetchTodos)

if (status === QueryStatus.Loading) {
  return <Spinner />
}

import { useQuery } from 'react-query'

const { status } = useQuery('todos', fetchTodos)

if (status === 'loading') {
  return <Spinner />
}

Enum values to string literals:

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

New Features

Query Data Selectors

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

Combine with notifyOnChangeProps for optimal performance:

useQuery('user', fetchUser, {
  select: (user) => user.username,
  notifyOnChangeProps: ['data', 'error'],
})

useQueries Hook

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>
)

Mutation Retry & Offline Support

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

// Mutations retry when device comes back online

Persist Mutations

Mutations can be persisted and resumed:

import { persistQueryClient } from 'react-query/persistQueryClient-experimental'
import { createWebStoragePersistor } from 'react-query/createWebStoragePersistor-experimental'

const persister = createWebStoragePersistor({ storage: window.localStorage })

persistQueryClient({
  queryClient,
  persister,
})

Query Observers

Watch queries outside React:

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

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

Also available:

• InfiniteQueryObserver
• QueriesObserver
• MutationObserver

Pre-Configure Queries

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

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

Pre-Configure Mutations

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

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

useIsFetching with Filters

const isFetchingPosts = useIsFetching(['posts'])

if (isFetchingPosts) {
  return <Spinner />
}

Core Separation

Use React Query core without React:

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

const queryClient = new QueryClient()

Devtools in Main Package

Before (v2)

import { ReactQueryDevtools } from 'react-query-devtools'

import { ReactQueryDevtools } from 'react-query/devtools'

Migration Checklist

1. Update QueryCache to QueryClient

   Replace all QueryCache instantiation with QueryClient.

2. Update Providers

   Replace ReactQueryCacheProvider and ReactQueryConfigProvider with QueryClientProvider.

3. Update Hook Names

   • useQueryCache → useQueryClient
   • usePaginatedQuery → useQuery with keepPreviousData
4. Update Infinite Queries

   Rename properties and update to use pages data structure.

5. Update Mutations

   Change from array to object destructuring.

6. Update Query Function Signatures

   Use inline functions or QueryFunctionContext.

7. Update Options

   Flatten config into main options object.

8. Update Method Names

   • getQuery → find
   • getQueries → findAll
   • clear → remove
9. Test Everything

   Thoroughly test all queries, mutations, and cache interactions.

v3 represents a major evolution of React Query with better architecture, improved TypeScript support, and many powerful new features.