# Upgrade a React App from React Router 5 to 6

Yes. An agent converts Switch, Redirect, useHistory and withRouter across your components, keeps the history your state machines use, runs the tests and opens a PR.

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

## What the agent does

The agent maps every place the router is used before changing any of them. In cypress-io/cypress-realworld-app, `package.json` pins React 18.2 with `react-router` and `react-router-dom` 5.3.4, `history` 4.10.1, MUI 5, XState 4.38 with `@xstate/react`, Vite 8 and Vitest 3, Cypress 16, Yarn 1.22.22, Node 22.20.0 in `.nvmrc`. 23 files under `src` import from the router. `containers/App.tsx` switches between `SignUpForm`, `SignInForm` and a catch-all `Redirect` to `/signin`; `containers/PrivateRoutesContainer.tsx` wraps six screens in a `PrivateRoute` inside a `Switch`, one with the regular-expression path `/(public|contacts|personal)?` and one with `/bankaccounts*`; `components/PrivateRoute.tsx` uses `Route`'s `render` prop and a `Redirect` carrying `state.from`, typed with `RouteProps`; `TransactionNavTabs.tsx` picks the active tab from `useRouteMatch().url`; `useHistory` drives navigation in `BankAccountForm`, `TransactionCreateStepThree` and `TransactionItem`; `index.okta.tsx` wraps the app in `withRouter`; and all five entry files (`index.tsx`, `index.auth0.tsx`, `index.cognito.tsx`, `index.google.tsx`, `index.okta.tsx`) render `<Router history={history}>` with the browser history created in `utils/historyUtils.ts`. That object is the subtle part: `machines/authMachine.ts` imports it and calls `history.push('/signin')` and `history.push('/')` from inside XState actions, outside any component, and reads `history.location.pathname`. Tests to keep green: eight Vitest files in `src/__tests__` against the backend, five component tests ending in `.cy.tsx` (two of them wrap the component in `MemoryRouter`), and Cypress end-to-end specs, seven under `cypress/tests/ui`, nine API specs and four auth-provider specs; CI in `main.yml` runs `yarn types`, `yarn lint`, `yarn test:unit:ci` and `yarn build:ci` before the Cypress jobs in the `cypress/browsers:22.20.0` image.

The upgrade goes to `react-router-dom` 6, dropping the separate `react-router` import and both `@types/react-router*` packages because version 6 ships its own types, and moving `history` to 5, which is what the version 6 history router accepts. `Switch` becomes `Routes` and each `Route` takes an `element`; the regular-expression path becomes four explicit routes, `/`, `/public`, `/contacts` and `/personal`, sharing one element, because version 6 matches paths by segments and no longer takes expressions; `/bankaccounts*` becomes `/bankaccounts/*`. `PrivateRoute` is rewritten as a layout route: when logged in it renders `<Outlet />`, otherwise `<Navigate to='/signin' state={{ from: location }} replace />`, so the `from` state the sign-in form reads survives. `Redirect` becomes `Navigate`, `useHistory` becomes `useNavigate` in the three components, `useRouteMatch().url` becomes `useLocation().pathname`, and `withRouter` in the Okta entry becomes a small component calling `useNavigate` for `restoreOriginalUri`. For the shared history the agent uses `unstable_HistoryRouter` with the same `history` object in all five entries, so the XState machine's `history.push` calls and its `history.location.pathname` read keep working without touching the machines; the pull request names the `unstable_` prefix and the trade-off.

MUI's `Tab component={Link}` in the nav tabs and the `RouterLink` aliases in the nav bar work unchanged with version 6's `Link`. The two component tests that mount inside `MemoryRouter` keep doing so, since `MemoryRouter` still exists, but their inner `Route` usage is updated the same way as the app. Cypress end-to-end specs visit URLs and read `data-test` attributes, so they need no change and are the best proof that the routes still resolve.

Verification follows `main.yml` in order: `yarn types`, `yarn lint`, `yarn test:unit:ci` and `yarn build:ci`, then `yarn cypress:run:component` for the five component tests, and `yarn start:ci` with `yarn cypress:run --spec 'cypress/tests/ui/*'` for the seven user-interface specs, which exercise sign-in, the transaction feeds and tabs, new transactions, bank accounts, notifications and user settings. The agent reports the counts it saw for each suite, fixes what fails, and leaves the version 7 future flags (`v7_startTransition`, `v7_relativeSplatPath`) on in the router so the next upgrade is a package rename.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Upgrade this React app from React Router 5 to React Router 6. Read package.json, every file under src that imports react-router or react-router-dom, src/utils/historyUtils.ts and the XState machines that import it, the component tests and the Cypress config first, and list each API in use: Switch, Route render props, Redirect, useHistory, useRouteMatch, withRouter, RouteProps and the Router with a custom history. Move to react-router-dom 6 and history 5, remove the separate react-router package and the DefinitelyTyped router packages, convert Switch to Routes with element props, replace the regular-expression route with explicit routes and the trailing-star route with a splat, rewrite PrivateRoute as a layout route using Outlet and Navigate that preserves the from state, replace Redirect, useHistory, useRouteMatch and withRouter with their version 6 equivalents, and keep the shared history object working for the state machines with the history router. Enable the version 7 future flags. Run the type check, lint, backend unit tests and production build, then the Cypress component tests and the user-interface end-to-end specs against the local servers, fix what breaks, and open a pull request listing every converted file and what each suite reported.",
  "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

What comes back is a pull request over `package.json` and `yarn.lock`, the five entry files, `containers/App.tsx`, `containers/PrivateRoutesContainer.tsx`, `components/PrivateRoute.tsx`, `TransactionNavTabs.tsx`, the three components that navigated with `useHistory`, and the two component tests. Its description lists each version 5 API with the file it lived in and what replaced it, explains the four explicit routes that stand in for the expression path, and states the result of each of the six suites it ran.

The run's record keeps the type check, lint and build output, the Vitest run, and the Cypress component and end-to-end runs with their pass and fail counts, so a reviewer can see which spec caught a wrong route and what changed in response.

Before merging, a reviewer reads `PrivateRoute` and the history router line, since those decide whether a logged-out user lands on sign-in and comes back to where they were, and lets `main.yml` run the full Cypress matrix on the pull request, which covers the Chrome and mobile viewport jobs the agent did not run.

## Run it on every app still on React Router 5

An organisation with several front ends can start this job for each one from a short script: for every repository the GitHub App reaches, read `package.json` from the default branch, and when `react-router-dom` resolves to a major version of 5 send this body with that repository as the `resources` URL. Give each request a `request_id` that is a UUID v5 of the repository's full name so a second run of the script returns the runs already started.

Each run opens its own pull request, and the key's `run.completed` webhook carries the session URL for each one, which is enough to build a list of what is waiting for review.

## Why run it on Rush?

A router upgrade is not hard in any one file; it is hard because there are twenty-three of them, two test runners and a state machine that navigates from outside React, and the only honest check is to run the whole application through its own end-to-end suite afterwards. The agent does that in a sandbox with a browser, with the real backend started the same way CI starts it, and keeps every suite's output.

Handed off from a terminal, the run finishes without anyone watching the Cypress window, and the pull request that is waiting says exactly which API moved where and what each suite reported, which is what a reviewer needs for a change that touches every screen.

## Frequently asked questions

### Why unstable_HistoryRouter instead of BrowserRouter?

The XState auth machine calls `history.push` from its actions, outside any component, and reads `history.location.pathname`. `BrowserRouter` owns its own history, so those calls would stop affecting the app. The history router accepts the existing `history` object, which keeps the machines untouched; the pull request names the `unstable_` prefix and suggests a navigate-based bridge as a follow-up if the team prefers.

### Why four routes instead of the one regular-expression path?

React Router 6 matches paths by segments and does not accept expressions. The version 5 path `/(public|contacts|personal)?` matched the root plus three tabs, so the agent declares `/`, `/public`, `/contacts` and `/personal` pointing at the same element, which also makes the tab lookup in `TransactionNavTabs` a plain pathname comparison.

### Do the Cypress tests need to change?

The end-to-end specs do not: they visit URLs and click `data-test` elements, so they are the proof the routes still resolve. The two component tests that mount a component inside `MemoryRouter` keep that wrapper and only update the inner `Route` syntax to version 6.

### Why not go straight to React Router 7?

Version 7 is the version 6 API with the future flags on and a single package. The agent turns on `v7_startTransition` and `v7_relativeSplatPath` in this pull request, so the move to 7 becomes a dependency rename in a later, small change rather than a second behavioural migration.

## More React jobs

- [Add Route-Based Code Splitting to a React App](https://getrush.ai/run/add-code-splitting/react/)
- [Add Dark Mode to a React App](https://getrush.ai/run/add-dark-mode/react/)
- [Add Error Boundaries to a React App](https://getrush.ai/run/add-error-boundaries/react/)

## More jobs like this: Hand off a long task

- [Upgrade an Astro Project's DAGs to Airflow 3](https://getrush.ai/run/upgrade-to-airflow-3/airflow/)
- [Add Accessibility Labels to an Expo App's Screens and Components](https://getrush.ai/run/add-accessibility-labels/expo/)
- [Add Accessibility Labels to a Flutter Cupertino App](https://getrush.ai/run/add-accessibility-labels/flutter/)

## 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/)
