Chapter 44: Migrating to React Query 4

Core Idea

v4 moved the package to the @tanstack scope, made query/mutation keys array-only everywhere (no more bare-string keys), removed the idle status in favor of the fetchStatus model, and introduced network-aware pausing (queries/mutations now default to waiting for connectivity instead of failing offline).

Key Concepts

• Package rename: react-query → @tanstack/react-query (+ separate @tanstack/react-query-devtools) — a codemod handles the import rewrite.
• Array-only keys: bare string keys (useQuery('todos', fetchTodos)) are no longer allowed — every key must be an array (useQuery(['todos'], fetchTodos)), for consistency across every API surface (filters, predicates, callbacks) that previously had to handle mixed string/array keys. A codemod automates this too.
• idle status removed: superseded by the fetchStatus model (Chapter 10) — a disabled query with no data now reports status: 'pending' + fetchStatus: 'idle' instead of the old status: 'idle'. Use isInitialLoading (the v4-era name for what's now called isLoading in v5) instead of isLoading to detect "actually fetching for the first time," since disabled queries now start in pending regardless of whether they're fetching.
• useQueries object argument: takes { queries: [...] } instead of a bare array, matching the shape later reused by queryOptions-style APIs.
• undefined becomes illegal as a successful cache value: a queryFn resolving to undefined (easy to do accidentally, e.g. by chaining .then(console.log) after the real logic) now produces a failed Promise/error at runtime, not a silently empty success — resolve null if "nothing" needs representing.
• Network-mode default flip: queries/mutations now pause by default without a network connection (see Network Mode, Chapter 14) — opt back into the pre-v4 "always try to fetch" behavior with networkMode: 'offlineFirst' set globally.
• notifyOnChangeProps: 'tracked' removed as an explicit value: tracked-properties re-render skipping (Chapter 39) is now simply the default — notifyOnChangeProps: 'all' is the new way to opt back into re-rendering on every change, and the separate notifyOnChangePropsExclusion option was removed as redundant.
• cancelRefetch now defaults to true: for every imperative refetch trigger (refetchQueries, invalidateQueries, resetQueries, refetch(), and infinite queries' fetchNextPage/fetchPreviousPage) — a second overlapping call now cancels and restarts the first fetch instead of silently no-op'ing, which fixes stale-result bugs when refetching was triggered twice in quick succession (e.g. after a mutation while a slow background fetch was already in flight).

Key Takeaways

1. Run both codemods (import rewrite, key-array transform) before manually touching anything — most of this migration is mechanical.
2. undefined-returning queryFns are a common accidental bug (e.g. a stray .then(console.log)) that v4 turns into a real, visible error instead of a silent no-op — audit queryFns for this pattern specifically when upgrading.
3. If the app relies on offline-tolerant fetch behavior, set networkMode: 'offlineFirst' explicitly — v4's new default (online) will otherwise pause queries/mutations without connectivity.

Connects To

• Network Mode: the pausing behavior introduced as the new default here.
• Render Optimizations: tracked properties, made the unconditional default in this version.
• Migrating to TanStack Query v5: the next major version's changes, including further renames of concepts introduced here (isInitialLoading → isLoading).