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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
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 (Redux)
- Replace the Deprecated request Package With Native fetch (request)
- Replace rimraf and mkdirp With fs.rm and fs.mkdir in a Node.js Package (rimraf)
- Migrate Sass @import to @use and Clear the Dart Sass Deprecation Warnings (Sass)
- Migrate From satori/go.uuid to google/uuid in a Go App (satori/go.uuid)
- Migrate From sqlite3 to better-sqlite3 in a Node.js API (node-sqlite3)