# Migrate From React Query v3 to TanStack Query v5

Yes. The agent upgrades React and TypeScript first, runs the v4 and v5 codemods in order, then repairs the callbacks and loading flags the codemods get wrong.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-react-query-to-tanstack-query/react-query/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the versions the new library will have to live with. In an app like bezkoder/react-query-axios-typescript, `package.json` has `react-query` ^3.29.0, React ^17.0.2, `react-scripts` 4.0.3 and `typescript` ^4.1.2, which `yarn.lock` resolves to 4.4.4. `src/index.tsx` creates the `QueryClient` and renders with `ReactDOM.render`. `src/App.tsx` holds all seven hooks: three `useQuery` calls written as key string, function, options, each with `enabled: false` and started from a button through `refetch`, and four `useMutation` calls. Every one of them reports through `onSuccess` and `onError` callbacks and has a `useEffect` that watches `isLoading`. A baseline comes first, and on current Node the build script dies before compiling, with `ERR_PACKAGE_PATH_NOT_EXPORTED` from a nested `postcss`. On Node 16 the same condition is a deprecation warning and the build completes, so the agent takes its baseline there and says so.

It then shows why the shortcut is dangerous. Installing `@tanstack/react-query` and renaming the two imports produces a build that says `Compiled successfully`. Nothing about that app works. TanStack Query v5 declares React 18 as a peer and calls `useSyncExternalStore`, which React 17 does not have. TypeScript 4.4.4 cannot parse the library's declaration files: `tsc --noEmit` lists 62 syntax errors, every one inside the package's own `.d.ts` files and none in `src`, and the build's checker lets that pass. With the types unreadable, nothing flags that v5 accepts only a single options object, a mistake the library itself reports only as a development-time exception. So the agent upgrades the ground first: React and React DOM to 18 with `createRoot` in `src/index.tsx`, the React type packages, and TypeScript to a release that reads the new declarations.

The codemods ship inside the package, under `build/codemods`, and their order matters for code coming from v3. Run directly on this file, the v5 `remove-overloads` transform does not recognise a string key and emits `useQuery({ queryKey: "query-tutorials", queryFn }, { enabled: false, ... })`. The second argument in v5 is a query client, so `enabled: false` silently stops applying. Running the v4 `key-transformation` transform first turns each key into an array, after which `remove-overloads` produces one correct options object. The agent runs them in that order and reads the result line by line, because three things are still wrong.

The transform drops the `<Tutorial[], Error>` type arguments, which the agent restores. It keeps `onSuccess` and `onError` inside the three `useQuery` calls, and v5 removed those callbacks from queries, so the result panels would never update; with a TypeScript that can read the types, `tsc` now points at exactly those three calls. Since each query here is fetched on a click, the agent uses what `refetch()` resolves with: the handler awaits it and writes `data` or `error` to the panel. The mutations keep their callbacks, which v5 still supports. Last, the `is-loading` transform renames `isLoading` to `isPending` on all seven hooks. That is right for the mutations. For a disabled query `isPending` is true from the first render, so each panel would say it is loading before anyone clicks. The agent leaves the three queries on v5's `isLoading`, which is true only while a first fetch is in flight.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Migrate this React app from react-query v3 to @tanstack/react-query v5. Read package.json, the lockfile, tsconfig.json, the file that creates the QueryClient and every file that calls useQuery, useMutation, useQueryClient or other query APIs. Report the resolved versions of react, react-dom, typescript and react-query, and for each hook call: its key, whether it is enabled, how it is triggered, which callbacks it passes and which status flags the component reads. Take a baseline build; if the build tool does not run on this machine's Node, find a Node version it does run on, use it, and say which. Before migrating, check TanStack Query v5's peer range for React and whether the installed TypeScript can parse its declaration files by running tsc --noEmit after installing it; upgrade React, its type packages and TypeScript as far as v5 requires and no further, and move the root to createRoot if React 18 is needed. Find the codemods inside the installed package and run the v4 ones before the v5 ones; show each diff. Then review the result by hand: restore type arguments the codemod dropped, replace query callbacks that v5 no longer calls with code that produces the same visible behaviour, keep mutation callbacks, and choose between isPending and isLoading per hook according to what the component showed before, paying attention to disabled queries. Do not change the API service, the markup or the build tool. Verify with tsc --noEmit, the production build, and a click-through of every button against a stub of the API the service calls, checking each result panel and loading text. Open a pull request with the hook table, each upgrade and why it was needed, the codemod diffs, the manual corrections, and the verification output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request is ordered so each commit explains the next. First the platform: React 18, its type packages, TypeScript and the `createRoot` change, with the old library still in place and the app building. Then the package swap and the two codemod commits, each exactly what the transform produced. Then one commit of manual corrections. A reviewer can read the last commit alone to see everything a person had to decide, and it is short: three queries, seven flags, the restored type arguments.

The description carries the hook table from the inventory with a column for what changed in each: its key as an array, where its success and error handling moved, and which flag its loading text now reads. It also records the demonstration from the start, that a rename-only change builds green on the old toolchain while `tsc` reports errors in the library's declarations, so the reason for the platform commits is on the page. `tsc --noEmit` and the build output for the final state follow.

What a reviewer should try before merging is the first paint. Load the page and confirm that no panel says it is loading before a button is pressed, then press each of the seven action buttons against a running API and watch the panel fill. Those are the two behaviours the automatic transforms would have broken without any compile error on the original toolchain. The pull request notes that `react-scripts` 4 still needs an older Node to build and leaves that upgrade for its own change.

## Run it on every first of the month

Major upgrades of a data-fetching library are easier when they never fall two versions behind. Add an automation to the Project in the console with a `schedule` trigger, `cron` set to `0 9 1 * *` and your `timezone`, and a saved prompt that asks the agent to compare the installed major of the query library with the latest, and if they differ, to take one major step with that step's codemods, the manual review described above, and the verification output. If they match, the prompt tells it to answer in one line and open nothing.

Each fire starts one run in the Project's repository, as the member who last changed the automation. Because the run begins from a clean checkout, a step that needs a newer React or TypeScript is discovered and reported at that point, not when someone finally has to upgrade under pressure.

## Why run it on Rush?

The lesson of this fixture is that a green build proves little here. The failures are in what the type checker could not read and in what the screen shows at first paint, and finding them takes several toolchains: an old Node to build at all, the old TypeScript to show the false green, a new one to get real errors, and a browser to press the buttons. The agent assembles those in one sandbox and records every command and its output in the session's transcript, so each statement in the pull request traces to something that ran.

It also gives the codemods the scrutiny they need. A transform that silently moves options into the wrong argument is only caught by someone who runs it both ways and reads the output. That is slow, careful work a person tends to skip on a Friday. A run does it every time, on its own machine, while the team keeps working, and what comes back is a pull request whose last commit is exactly the set of human decisions.

## Frequently asked questions

### Do I have to go through v4 first?

You do not have to release on v4, but its codemods have to run before the v5 ones. The v4 step renames the package and turns string keys into arrays, and the v5 transform assumes that has happened. The agent runs both sets in order inside one pull request and installs only v5.

### What replaces onSuccess and onError on useQuery?

It depends on what they did. For a query triggered by a button, the promise from `refetch()` resolves with the result, so the click handler can act on it. For side effects that follow automatic fetches, the usual answers are deriving from `data` and `error` during render or a global handler on the query cache. The agent picks per call and explains each choice.

### Why is isLoading different in v5?

v5 renamed the old meaning to `isPending`, which is true whenever a query has no data yet, including a disabled query that has never run. The name `isLoading` now means pending and currently fetching. A component that showed a spinner only during a fetch wants `isLoading`; one that showed it until data existed wants `isPending`.

### Can I stay on React 17?

Not with v5, whose peer range starts at React 18. If React cannot move yet, v4 is the furthest this library can go, and the agent will stop there and say what blocks the last step.

## More jobs like this: Upgrade dependencies weekly

- [Migrate a React App From Redux to Redux Toolkit](https://getrush.ai/run/migrate-redux-to-redux-toolkit/redux/)
- [Replace the Deprecated request Package With Native fetch](https://getrush.ai/run/migrate-request-to-fetch/request/)
- [Replace rimraf and mkdirp With fs.rm and fs.mkdir in a Node.js Package](https://getrush.ai/run/migrate-rimraf-to-fs-rm/rimraf/)
- [Migrate Sass @import to @use and Clear the Dart Sass Deprecation Warnings](https://getrush.ai/run/migrate-sass-import-to-use/sass/)
- [Migrate From satori/go.uuid to google/uuid in a Go App](https://getrush.ai/run/migrate-satori-uuid-to-google-uuid/satori-uuid/)
- [Migrate From sqlite3 to better-sqlite3 in a Node.js API](https://getrush.ai/run/migrate-sqlite3-to-better-sqlite3/sqlite3/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
