Skip to content
Home / Migrations / TanStack Query v4TanStack Query v5

TanStack Query v4 TanStack Query v5

medium

v5 simplifies the API to single-object signatures and renames a few options. Most upgrades take an hour with the codemod.

Estimated: 2-5h · 5 steps
Progress0%
Step 1: Run codemod
npx @tanstack/query-codemods v5/remove-overloads.cjs ./src
Step 2: Rename cacheTime → gcTime

Find/replace across the codebase or rely on the codemod.

Step 3: Remove onSuccess/onError/onSettled

Side effects move to useEffect or to mutation-level callbacks. useQuery callbacks were removed.

useEffect(() => { if (query.data) trackEvent('loaded') }, [query.data])
Step 4: Switch isLoading semantics

isLoading → isPending (no cached data + first fetch). isFetching unchanged. Update conditions accordingly.

Step 5: Update Suspense usage

Use useSuspenseQuery instead of useQuery({ suspense: true }).

All queries refetch correctly. No type errors. Devtools show v5.

What this migration involves

Moving from TanStack Query v4 to TanStack Query v5 is rated medium and takes about 2-5h on a typical project. The guide breaks it into 5 steps, 2 of which ship with runnable commands and 1 with a verification check.

FAQ

How long does migrating from TanStack Query v4 to TanStack Query v5 take?

Around 2-5h for a typical project — 5 steps, difficulty rated medium, 2 of them with copy-paste commands.

Is moving from TanStack Query v4 to TanStack Query v5 reversible?

No reverse guide is tracked yet, so treat this as a one-way move and keep a full export of your TanStack Query v4 data before you start.

What does TanStack Query v5 cost compared to TanStack Query v4?

Pricing for both tools is contact-based or not tracked yet.