TanStack Query v5 introduces several breaking changes and improvements. Here’s a detailed overview:
1. Unified Object Signature
Previously, useQuery and similar hooks had multiple overloads. Now, they all use a single object format:
// Old
useQuery(key, fn, options);
useInfiniteQuery(key, fn, options);
useMutation(fn, options);
// New
useQuery({ queryKey, queryFn, ...options });
useInfiniteQuery({ queryKey, queryFn, ...options });
useMutation({ mutationFn, ...options });2. Query Client Methods
Methods on queryClient and queryCache now also use the unified object format:
// Old
queryClient.isFetching(key, filters);
queryClient.ensureQueryData(key, filters);
// New
queryClient.isFetching({ queryKey, ...filters });
queryClient.ensureQueryData({ queryKey, ...filters });3. Simplified Query State Methods
Methods getQueryData and getQueryState now only accept queryKey:
// Old
queryClient.getQueryData(queryKey, filters);
// New
queryClient.getQueryData(queryKey);4. Removed Callbacks from useQuery
Callbacks like onSuccess, onError, and onSettled are removed from useQuery and QueryObserver.
5. New Refetch Interval
refetchInterval now only gets query passed:
// Old
refetchInterval: number | false | ((data, query) => number | false | undefined);
// New
refetchInterval: number | false | ((query) => number | false | undefined);6. Remove Method
remove method is removed from useQuery. Use queryClient.removeQueries({queryKey: key}) instead:
const queryClient = useQueryClient();
const query = useQuery({ queryKey, queryFn });
// Old
query.remove();
// New
queryClient.removeQueries({ queryKey });7. Minimum TypeScript Version
The minimum required TypeScript version is now 4.7.
8. isDataEqual Option Removed
Use structuralSharing instead:
import { replaceEqualDeep } from '@tanstack/react-query';
// Old
isDataEqual: (oldData, newData) => customCheck(oldData, newData);
// New
structuralSharing: (oldData, newData) => customCheck(oldData, newData) ? oldData : replaceEqualDeep(oldData, newData);9. Rename cacheTime to gcTime
Reflects its true purpose as “garbage collect” time:
const queryClient = new QueryClient({
defaultOptions: {
queries: {
// Old
cacheTime: 10 * MINUTE,
// New
gcTime: 10 * MINUTE,
},
},
});10. useErrorBoundary Renamed
Renamed to throwOnError for clarity:
// Old
useErrorBoundary: true;
// New
throwOnError: true;11. Removed Deprecated keepPreviousData
Use placeholderData with an identity function instead:
import { useQuery, keepPreviousData } from "@tanstack/react-query";
const { data, isPlaceholderData } = useQuery({
queryKey,
queryFn,
placeholderData: keepPreviousData,
});12. Refetch on Focus and Network Status Changes
visibilitychange event is used exclusively for refetching on focus. navigator.onLine is no longer relied upon.
13. Removed Custom Context Prop
Pass a custom queryClient instance directly to isolate hooks:
import { queryClient } from './my-client';
const { data } = useQuery({
queryKey: ['users', id],
queryFn: () => fetch(...),
queryClient,
});14. New Hydration API
Hydrate component renamed to HydrationBoundary:
// Old
import { Hydrate } from '@tanstack/react-query';
// New
import { HydrationBoundary } from '@tanstack/react-query';15. Removed Manual Mode for Infinite Queries
Use getNextPageParam and getPreviousPageParam instead:
useInfiniteQuery({
queryKey,
queryFn: ({ pageParam }) => fetchSomething(pageParam),
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.next,
});16. New Features
- Optimistic Updates: Simplified way to perform optimistic updates.
- Limited Infinite Queries: Use the maxPages option to limit stored pages.
- Enhanced Prefetching: Prefetch multiple pages for infinite queries.
Migration Guide
To ease the migration, use the provided codemod:
# For .js or .jsx files
npx jscodeshift@latest ./path/to/src/ \
--extensions=js,jsx \
--transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs
# For .ts or .tsx files
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.cjsRemember to run prettier and/or eslint after applying the codemod.
By following these guidelines, you can smoothly transition to TanStack Query v5 and take advantage of its new features and improvements.
