v5 is a major version, so there are some breaking changes to be aware of:
useQuery and friends used to have many overloads in TypeScript - different ways how the function can be invoked. Not only this was tough to maintain, type wise, it also required a runtime check to see which type the first and the second parameter, to correctly create options.
now we only support the object format.
;-useQuery(key, fn, options) + // [!code --]
useQuery({ queryKey, queryFn, ...options }) - // [!code ++]
useInfiniteQuery(key, fn, options) + // [!code --]
useInfiniteQuery({ queryKey, queryFn, ...options }) - // [!code ++]
useMutation(fn, options) + // [!code --]
useMutation({ mutationFn, ...options }) - // [!code ++]
useIsFetching(key, filters) + // [!code --]
useIsFetching({ queryKey, ...filters }) - // [!code ++]
useIsMutating(key, filters) + // [!code --]
useIsMutating({ mutationKey, ...filters }) // [!code ++]
;-useQuery(key, fn, options) + // [!code --]
useQuery({ queryKey, queryFn, ...options }) - // [!code ++]
useInfiniteQuery(key, fn, options) + // [!code --]
useInfiniteQuery({ queryKey, queryFn, ...options }) - // [!code ++]
useMutation(fn, options) + // [!code --]
useMutation({ mutationFn, ...options }) - // [!code ++]
useIsFetching(key, filters) + // [!code --]
useIsFetching({ queryKey, ...filters }) - // [!code ++]
useIsMutating(key, filters) + // [!code --]
useIsMutating({ mutationKey, ...filters }) // [!code ++]
;-queryClient.isFetching(key, filters) + // [!code --]
queryClient.isFetching({ queryKey, ...filters }) - // [!code ++]
queryClient.ensureQueryData(key, filters) + // [!code --]
queryClient.ensureQueryData({ queryKey, ...filters }) - // [!code ++]
queryClient.getQueriesData(key, filters) + // [!code --]
queryClient.getQueriesData({ queryKey, ...filters }) - // [!code ++]
queryClient.setQueriesData(key, updater, filters, options) + // [!code --]
queryClient.setQueriesData({ queryKey, ...filters }, updater, options) - // [!code ++]
queryClient.removeQueries(key, filters) + // [!code --]
queryClient.removeQueries({ queryKey, ...filters }) - // [!code ++]
queryClient.resetQueries(key, filters, options) + // [!code --]
queryClient.resetQueries({ queryKey, ...filters }, options) - // [!code ++]
queryClient.cancelQueries(key, filters, options) + // [!code --]
queryClient.cancelQueries({ queryKey, ...filters }, options) - // [!code ++]
queryClient.invalidateQueries(key, filters, options) + // [!code --]
queryClient.invalidateQueries({ queryKey, ...filters }, options) - // [!code ++]
queryClient.refetchQueries(key, filters, options) + // [!code --]
queryClient.refetchQueries({ queryKey, ...filters }, options) - // [!code ++]
queryClient.fetchQuery(key, fn, options) + // [!code --]
queryClient.fetchQuery({ queryKey, queryFn, ...options }) - // [!code ++]
queryClient.prefetchQuery(key, fn, options) + // [!code --]
queryClient.prefetchQuery({ queryKey, queryFn, ...options }) - // [!code ++]
queryClient.fetchInfiniteQuery(key, fn, options) + // [!code --]
queryClient.fetchInfiniteQuery({ queryKey, queryFn, ...options }) - // [!code ++]
queryClient.prefetchInfiniteQuery(key, fn, options) + // [!code --]
queryClient.prefetchInfiniteQuery({ queryKey, queryFn, ...options }) // [!code ++]
;-queryClient.isFetching(key, filters) + // [!code --]
queryClient.isFetching({ queryKey, ...filters }) - // [!code ++]
queryClient.ensureQueryData(key, filters) + // [!code --]
queryClient.ensureQueryData({ queryKey, ...filters }) - // [!code ++]
queryClient.getQueriesData(key, filters) + // [!code --]
queryClient.getQueriesData({ queryKey, ...filters }) - // [!code ++]
queryClient.setQueriesData(key, updater, filters, options) + // [!code --]
queryClient.setQueriesData({ queryKey, ...filters }, updater, options) - // [!code ++]
queryClient.removeQueries(key, filters) + // [!code --]
queryClient.removeQueries({ queryKey, ...filters }) - // [!code ++]
queryClient.resetQueries(key, filters, options) + // [!code --]
queryClient.resetQueries({ queryKey, ...filters }, options) - // [!code ++]
queryClient.cancelQueries(key, filters, options) + // [!code --]
queryClient.cancelQueries({ queryKey, ...filters }, options) - // [!code ++]
queryClient.invalidateQueries(key, filters, options) + // [!code --]
queryClient.invalidateQueries({ queryKey, ...filters }, options) - // [!code ++]
queryClient.refetchQueries(key, filters, options) + // [!code --]
queryClient.refetchQueries({ queryKey, ...filters }, options) - // [!code ++]
queryClient.fetchQuery(key, fn, options) + // [!code --]
queryClient.fetchQuery({ queryKey, queryFn, ...options }) - // [!code ++]
queryClient.prefetchQuery(key, fn, options) + // [!code --]
queryClient.prefetchQuery({ queryKey, queryFn, ...options }) - // [!code ++]
queryClient.fetchInfiniteQuery(key, fn, options) + // [!code --]
queryClient.fetchInfiniteQuery({ queryKey, queryFn, ...options }) - // [!code ++]
queryClient.prefetchInfiniteQuery(key, fn, options) + // [!code --]
queryClient.prefetchInfiniteQuery({ queryKey, queryFn, ...options }) // [!code ++]
;-queryCache.find(key, filters) + // [!code --]
queryCache.find({ queryKey, ...filters }) - // [!code ++]
queryCache.findAll(key, filters) + // [!code --]
queryCache.findAll({ queryKey, ...filters }) // [!code ++]
;-queryCache.find(key, filters) + // [!code --]
queryCache.find({ queryKey, ...filters }) - // [!code ++]
queryCache.findAll(key, filters) + // [!code --]
queryCache.findAll({ queryKey, ...filters }) // [!code ++]
queryClient.getQueryData argument is changed to accept only a queryKey
;-queryClient.getQueryData(queryKey, filters) + // [!code --]
queryClient.getQueryData(queryKey) // [!code ++]
;-queryClient.getQueryData(queryKey, filters) + // [!code --]
queryClient.getQueryData(queryKey) // [!code ++]
queryClient.getQueryState argument is changed to accept only a queryKey
;-queryClient.getQueryState(queryKey, filters) + // [!code --]
queryClient.getQueryState(queryKey) // [!code ++]
;-queryClient.getQueryState(queryKey, filters) + // [!code --]
queryClient.getQueryState(queryKey) // [!code ++]
To make the remove overloads migration easier, v5 comes with a codemod.
The codemod is a best efforts attempt to help you migrate the breaking change. Please review the generated code thoroughly! Also, there are edge cases that cannot be found by the code mod, so please keep an eye on the log output.
If you want to run it against .js or .jsx files, please use the command below:
npx jscodeshift@latest ./path/to/src/ \
--extensions=js,jsx \
--transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs
npx jscodeshift@latest ./path/to/src/ \
--extensions=js,jsx \
--transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs
If you want to run it against .ts or .tsx files, please use the command below:
npx jscodeshift@latest ./path/to/src/ \
--extensions=ts,tsx \
--parser=tsx \
--transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs
npx jscodeshift@latest ./path/to/src/ \
--extensions=ts,tsx \
--parser=tsx \
--transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs
Please note in the case of TypeScript you need to use tsx as the parser; otherwise, the codemod won't be applied properly!
Note: Applying the codemod might break your code formatting, so please don't forget to run prettier and/or eslint after you've applied the codemod!
A few notes about how codemod works:
onSuccess, onError and onSettled have been removed from Queries. They haven't been touched for Mutations. Please see this RFC for motivations behind this change and what to do instead.
This streamlines how callbacks are invoked (the refetchOnWindowFocus, refetchOnMount and refetchOnReconnect callbacks all only get the query passed as well), and it fixes some typing issues when callbacks get data transformed by select.
- refetchInterval: number | false | ((data: TData | undefined, query: Query) => number | false | undefined) // [!code --]
+ refetchInterval: number | false | ((query: Query) => number | false | undefined) // [!code ++]
- refetchInterval: number | false | ((data: TData | undefined, query: Query) => number | false | undefined) // [!code --]
+ refetchInterval: number | false | ((query: Query) => number | false | undefined) // [!code ++]
You can still access data with query.state.data, however, it will not be data that has been transformed by select. If you need to access the transformed data, you can call the transformation again on query.state.data.
Previously, remove method used to remove the query from the queryCache without informing observers about it. It was best used to remove data imperatively that is no longer needed, e.g. when logging a user out.
But It doesn't make much sense to do this while a query is still active, because it will just trigger a hard loading state with the next re-render.
if you still need to remove a query, you can use queryClient.removeQueries({queryKey: key})
const queryClient = useQueryClient()
const query = useQuery({ queryKey, queryFn })
;-query.remove() + // [!code --]
queryClient.removeQueries({ queryKey }) // [!code ++]
const queryClient = useQueryClient()
const query = useQuery({ queryKey, queryFn })
;-query.remove() + // [!code --]
queryClient.removeQueries({ queryKey }) // [!code ++]
Mainly because an important fix was shipped around type inference. Please see this TypeScript issue for more information.
Previously, This function was used to indicate whether to use previous data (true) or new data (false) as a resolved data for the query.
You can achieve the same functionality by passing a function to structuralSharing instead:
import { replaceEqualDeep } from '@tanstack/react-query'
- isDataEqual: (oldData, newData) => customCheck(oldData, newData) // [!code --]
+ structuralSharing: (oldData, newData) => customCheck(oldData, newData) ? oldData : replaceEqualDeep(oldData, newData) // [!code ++]
import { replaceEqualDeep } from '@tanstack/react-query'
- isDataEqual: (oldData, newData) => customCheck(oldData, newData) // [!code --]
+ structuralSharing: (oldData, newData) => customCheck(oldData, newData) ? oldData : replaceEqualDeep(oldData, newData) // [!code ++]
Custom loggers were already deprecated in 4 and have been removed in this version. Logging only had an effect in development mode, where passing a custom logger is not necessary.
We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements here.
TanStack Query has always had private fields and methods on classes, but they weren't really private - they were just private in TypeScript. We now use ECMAScript Private class features, which means those fields are now truly private and can't be accessed from the outside at runtime.
Almost everyone gets cacheTime wrong. It sounds like "the amount of time that data is cached for", but that is not correct.
cacheTime does nothing as long as a query is still in use. It only kicks in as soon as the query becomes unused. After the time has passed, data will be "garbage collected" to avoid the cache from growing.
gc is referring to "garbage collect" time. It's a bit more technical, but also a quite well known abbreviation in computer science.
const MINUTE = 1000 * 60;
const queryClient = new QueryClient({
defaultOptions: {
queries: {
- cacheTime: 10 * MINUTE, // [!code --]
+ gcTime: 10 * MINUTE, // [!code ++]
},
},
})
const MINUTE = 1000 * 60;
const queryClient = new QueryClient({
defaultOptions: {
queries: {
- cacheTime: 10 * MINUTE, // [!code --]
+ gcTime: 10 * MINUTE, // [!code ++]
},
},
})
To make the useErrorBoundary option more framework-agnostic and avoid confusion with the established React function prefix "use" for hooks and the "ErrorBoundary" component name, it has been renamed to throwOnError to more accurately reflect its functionality.
Even though in JavaScript, you can throw anything (which makes unknown the most correct type), almost always, Errors (or subclasses of Error) are thrown. This change makes it easier to work with the error field in TypeScript for most cases.
If you want to throw something that isn't an Error, you'll now have to set the generic for yourself:
useQuery<number, string>({
queryKey: ['some-query'],
queryFn: async () => {
if (Math.random() > 0.5) {
throw 'some error'
}
return 42
},
})
useQuery<number, string>({
queryKey: ['some-query'],
queryFn: async () => {
if (Math.random() > 0.5) {
throw 'some error'
}
return 42
},
})
For a way to set a different kind of Error globally, see the TypeScript Guide.
Since the only supported syntax now is the object syntax, this rule is no longer needed
We have removed the keepPreviousData option and isPreviousData flag as they were doing mostly the same thing as placeholderData and isPlaceholderData flag.
To achieve the same functionality as keepPreviousData, we have added previous query data as an argument to placeholderData which accepts an identity function. Therefore you just need to provide an identity function to placeholderData or use the included keepPreviousData function from Tanstack Query.
A note here is that useQueries would not receive previousData in the placeholderData function as argument. This is due to a dynamic nature of queries passed in the array, which may lead to a different shape of result from placeholder and queryFn.
import {
useQuery,
+ keepPreviousData // [!code ++]
} from "@tanstack/react-query";
const {
data,
- isPreviousData, // [!code --]
+ isPlaceholderData, // [!code ++]
} = useQuery({
queryKey,
queryFn,
- keepPreviousData: true, // [!code --]
+ placeholderData: keepPreviousData // [!code ++]
});
import {
useQuery,
+ keepPreviousData // [!code ++]
} from "@tanstack/react-query";
const {
data,
- isPreviousData, // [!code --]
+ isPlaceholderData, // [!code ++]
} = useQuery({
queryKey,
queryFn,
- keepPreviousData: true, // [!code --]
+ placeholderData: keepPreviousData // [!code ++]
});
An identity function, in the context of Tanstack Query, refers to a function that always returns its provided argument (i.e. data) unchanged.
useQuery({
queryKey,
queryFn,
placeholderData: (previousData, previousQuery) => previousData, // identity function with the same behaviour as `keepPreviousData`
})
useQuery({
queryKey,
queryFn,
placeholderData: (previousData, previousQuery) => previousData, // identity function with the same behaviour as `keepPreviousData`
})
There are some caveats to this change however, which you must be aware of:
placeholderData will always put you into success state, while keepPreviousData gave you the status of the previous query. That status could be error if we have data fetched successfully and then got a background refetch error. However, the error itself was not shared, so we decided to stick with behavior of placeholderData.
keepPreviousData gave you the dataUpdatedAt timestamp of the previous data, while with placeholderData, dataUpdatedAt will stay at 0. This might be annoying if you want to show that timestamp continuously on screen. However you might get around it with useEffect.
const [updatedAt, setUpdatedAt] = useState(0)
const { data, dataUpdatedAt } = useQuery({
queryKey: ['projects', page],
queryFn: () => fetchProjects(page),
})
useEffect(() => {
if (dataUpdatedAt > updatedAt) {
setUpdatedAt(dataUpdatedAt)
}
}, [dataUpdatedAt])
const [updatedAt, setUpdatedAt] = useState(0)
const { data, dataUpdatedAt } = useQuery({
queryKey: ['projects', page],
queryFn: () => fetchProjects(page),
})
useEffect(() => {
if (dataUpdatedAt > updatedAt) {
setUpdatedAt(dataUpdatedAt)
}
}, [dataUpdatedAt])
The visibilitychange event is used exclusively now. This is possible because we only support browsers that support the visibilitychange event. This fixes a bunch of issues as listed here.
navigator.onLine doesn't work well in Chromium based browsers. There are a lot of issues around false negatives, which lead to Queries being wrongfully marked as offline.
To circumvent this, we now always start with online: true and only listen to online and offline events to update the status.
This should reduce the likelihood of false negatives, however, it might mean false positives for offline apps that load via serviceWorkers, which can work even without an internet connection.
In v4, we introduced the possibility to pass a custom context to all react-query hooks. This allowed for proper isolation when using MicroFrontends.
However, context is a react-only feature. All that context does is give us access to the queryClient. We could achieve the same isolation by allowing to pass in a custom queryClient directly. This in turn will enable other frameworks to have the same functionality in a framework-agnostic way.
import { queryClient } from './my-client'
const { data } = useQuery(
{
queryKey: ['users', id],
queryFn: () => fetch(...),
- context: customContext // [!code --]
},
+ queryClient, // [!code ++]
)
import { queryClient } from './my-client'
const { data } = useQuery(
{
queryKey: ['users', id],
queryFn: () => fetch(...),
- context: customContext // [!code --]
},
+ queryClient, // [!code ++]
)
In v4, we introduced the possibility to define the pages to refetch for infinite queries with the refetchPage function.
However, refetching all pages might lead to UI inconsistencies. Also, this option is available on e.g. queryClient.refetchQueries, but it only does something for infinite queries, not "normal" queries.
The v5 includes a new maxPages option for infinite queries to limit the number of pages to store in the query data and to refetch. This new feature handles the use cases initially identified for the refetchPage page feature without the related issues.
The options you can pass to dehydrate have been simplified. Queries and Mutations are always dehydrated (according to the default function implementation). To change this behaviour, instead of using the removed boolean options dehydrateMutations and dehydrateQueries you can implement the function equivalents shouldDehydrateQuery or shouldDehydrateMutation instead. To get the old behaviour of not hydrating queries/mutations at all, pass in () => false.
- dehydrateMutations?: boolean // [!code --]
- dehydrateQueries?: boolean // [!code --]
- dehydrateMutations?: boolean // [!code --]
- dehydrateQueries?: boolean // [!code --]
Previously, we've passed undefined to the queryFn as pageParam, and you could assign a default value to the pageParam parameter in the queryFn function signature. This had the drawback of storing undefined in the queryCache, which is not serializable.
Instead, you now have to pass an explicit initialPageParam to the infinite query options. This will be used as the pageParam for the first page:
useInfiniteQuery({
queryKey,
- queryFn: ({ pageParam = 0 }) => fetchSomething(pageParam), // [!code --]
+ queryFn: ({ pageParam }) => fetchSomething(pageParam), // [!code ++]
+ initialPageParam: 0, // [!code ++]
getNextPageParam: (lastPage) => lastPage.next,
})
useInfiniteQuery({
queryKey,
- queryFn: ({ pageParam = 0 }) => fetchSomething(pageParam), // [!code --]
+ queryFn: ({ pageParam }) => fetchSomething(pageParam), // [!code ++]
+ initialPageParam: 0, // [!code ++]
getNextPageParam: (lastPage) => lastPage.next,
})
Previously, we've allowed to overwrite the pageParams that would be returned from getNextPageParam or getPreviousPageParam by passing a pageParam value directly to fetchNextPage or fetchPreviousPage. This feature didn't work at all with refetches and wasn't widely known or used. This also means that getNextPageParam is now required for infinite queries.
In v4, you needed to explicitly return undefined to indicate that there is no further page available. We've widened this check to include null.
On the server, retry now defaults to 0 instead of 3. For prefetching, we have always defaulted to 0 retries, but since queries that have suspense enabled can now execute directly on the server as well (since React18), we have to make sure that we don't retry on the server at all.
The loading status has been renamed to pending, and similarly the derived isLoading flag has been renamed to isPending.
For mutations as well the status has been changed from loading to pending and the isLoading flag has been changed to isPending.
Lastly, a new derived isLoading flag has been added to the queries that is implemented as isPending && isFetching. This means that isLoading and isInitialLoading have the same thing, but isInitialLoading is deprecated now and will be removed in the next major version.
To understand the reasoning behind this change checkout the v5 roadmap discussion.
because it also hashes mutation keys and can be used inside the predicate functions of useIsMutating and useMutationState, which gets mutations passed.
To fix compatibility with Vue 2, useQueries composable now returns queries array wrapped in ref. Previously reactive was returned which led to multiple problems:
With this change all of those issues are fixed.
Also this aligns useQueries with other composables which return all of the values as refs.
To be able to provide new features following Vue releases, we now require Vue 3 to be at least in v3.3 version. Requirements for Vue 2.x remain unchanged.
v5 also comes with new features:
We have a new, simplified way to perform optimistic updates by leveraging the returned variables from useMutation:
const queryInfo = useTodos()
const addTodoMutation = useMutation({
mutationFn: (newTodo: string) => axios.post('/api/data', { text: newTodo }),
onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})
if (queryInfo.data) {
return (
<ul>
{queryInfo.data.items.map((todo) => (
<li key={todo.id}>{todo.text}</li>
))}
{addTodoMutation.isPending && (
<li key={String(addTodoMutation.submittedAt)} style={{ opacity: 0.5 }}>
{addTodoMutation.variables}
</li>
)}
</ul>
)
}
const queryInfo = useTodos()
const addTodoMutation = useMutation({
mutationFn: (newTodo: string) => axios.post('/api/data', { text: newTodo }),
onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})
if (queryInfo.data) {
return (
<ul>
{queryInfo.data.items.map((todo) => (
<li key={todo.id}>{todo.text}</li>
))}
{addTodoMutation.isPending && (
<li key={String(addTodoMutation.submittedAt)} style={{ opacity: 0.5 }}>
{addTodoMutation.variables}
</li>
)}
</ul>
)
}
Here, we are only changing how the UI looks when the mutation is running instead of writing data directly to the cache. This works best if we only have one place where we need to show the optimistic update. For more details, have a look at the optimistic updates documentation.
Infinite queries are great when infinite scroll or pagination are needed. However, the more pages you fetch, the more memory you consume, and this also slows down the query refetching process as all the pages are sequentially refetched.
Version 5 has a new maxPages option for infinite queries, which allows developers to limit the number of pages that are stored in the query data and subsequently refetched. You can adjust the maxPages value according to the UX and refetching performance you want to deliver.
Note that the infinite list must be bi-directional, which requires both getNextPageParam and getPreviousPageParam to be defined.
Infinite Queries can be prefetched like regular Queries. Per default, only the first page of the Query will be prefetched and will be stored under the given QueryKey. If you want to prefetch more than one page, you can use the pages option. Read the prefetching guide for more information.
See the useQueries docs for more details.
See the experimental_createPersister docs for more details.
Previously vue-query composables could be run only within setup function of the component.
We had an escape hatch in place to allow those hooks to be run anywhere if user would provide queryClient as a composable option.
Now you can use vue-query composables in any function that supports injectionContext. Ex. router navigation guards. When using this new feature, make sure that vue-query composable is running within effectScope. Otherwise it might lead to memory leaks. We have added dev-only warnings to inform users about potential misusage.