npm / @tanstack/react-query
@tanstack/react-query
What changed in @tanstack/react-query 4 to 5, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-17.
6 breaking3 new APIs and options4 behavior and defaults1 tooling15 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@tanstack/react-query 525 changes
Breaking changes 6
The unused experimental_afterQuery hook has been removed.
The unused experimental_beforeQuery hook has been removed.
The promise property has been removed from query results.
Experimental render-time prefetching has been removed.
placeholderData has been removed from suspense infinite queries.
Adds environmentManager.
Behavior and default changes 4
TData now defaults to InfiniteData<TQueryFnData> to match hook generics.
usePrefetchInfiniteQuery now uses queryClient.infiniteQuery for prefetching.
usePrefetchQuery now uses queryClient.query for prefetching.
TData now defaults to InfiniteData<TQueryFnData> to match hook generics.
Tooling 1
Codemods no longer copy unnecessary files from the codemods project.
Fixes and other changes 14
useQueries and useSuspenseQueries now throw falsy errors to the error boundary.
Return types can be emitted in declaration files without leaking internal data tag symbols.
Return types can be emitted in declaration files without leaking internal data tag symbols.
Type-only exports no longer emit a runtime import.
Mutation variables become optional when undefined extends TVariables.
Generic type parameters now propagate to the useMutationState select callback.
Unsubscribed useQueries no longer show optimistic fetching.
useQuery return types retain NoInfer.
React Query no longer enters optimistic fetching state when the query is not subscribed.
Suspense queries now skip calling combine, preventing combine from running when queries would suspend.
Resolved an issue involving the excluded build directory.
Maintains error state on reset refetch when initialData is defined.
Allows retryOnMount when throwOnError is a function.
Prevents infinite render loops when useSuspenseQueries has duplicate queryKeys.
@tanstack/react-query 44 changes
New APIs and options 3
Adds mutationOptions to React Query v4 for configuring mutations.
Adds usePrefetchInfiniteQuery to react-query.
Adds usePrefetchQuery to react-query.
Fixes and other changes 1
Updated to support React 19 as a peer dependency correctly.