What the agent does
The agent maps the styling approach first, because it decides how much of the migration is mechanical. In an app like bezkoder/react-material-ui-examples, package.json has @material-ui/core ^4.11.0 on React 16.13.1 and react-scripts 3.4.3. Four files import from the library: src/App.js and the three components under src/components. Each is a class wrapped in withStyles(styles), and all four share one plain object exported from src/css-common.js. There is no theme, no ThemeProvider and no makeStyles. So the surface is small, and almost all the risk sits in how those JSS classes behave once the library's own styles are generated by Emotion.
Order matters before any code changes. MUI v5 declares React 17 or later as a peer, and the lockfile holds @material-ui/core 4.11.0, whose own peer range is React ^16.8.0 only. Asking npm for React 17 while that version is installed ends in ERESOLVE. The agent therefore takes the route the peer ranges allow: move v4 to its last release, 4.12, which accepts React 17, upgrade React and React DOM, and build. Only then does it swap the packages for @mui/material, @mui/styles, @emotion/react and @emotion/styled. On Node 17 or later each build needs NODE_OPTIONS=--openssl-legacy-provider, because this react-scripts bundles with webpack 4.
Next come the codemods, and the agent reads what they did instead of trusting the name. v5.0.0/preset-safe changes exactly the four files and only their import lines: components now come from @mui/material and withStyles from @mui/styles/withStyles. It leaves the five TextField elements alone, none of which sets variant. The default variant changed from standard in v4 to outlined in v5, so every text field in the app would change appearance without a line of JSX changing. The transform that prevents this, v5.0.0/variant-prop, is not part of the preset; the agent runs it separately and it adds variant="standard" in the three component files.
The last problem produces no error at all. With @mui/styles, JSS writes its <style> tag into the document head before Emotion writes the library's rules, and at equal specificity the later rule wins. The classes in css-common.js that set a single property on a single class lose: the dark backgroundColor on the AppBar, the blue, red and green backgrounds of the publish, delete and update buttons, and textTransform: "none" on every button. A rule such as '& .MuiToolbar-regular', which is more specific, survives. The fix is the one MUI documents: wrap the app in <StyledEngineProvider injectFirst> in src/index.js, which moves Emotion's tag ahead of JSS. The agent verifies the order of the style tags in a rendered page and compares screenshots of the list and add screens taken before the upgrade and after.
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 Material-UI v4 (@material-ui/core) to MUI v5 (@mui/material). Read package.json, the lockfile, src/index.js and every file that imports from @material-ui first. Report how styles are written (withStyles, makeStyles, a theme, plain CSS), which components and props are used, and the resolved versions of React and the library. Take a baseline build and screenshots of each route. Check the peer dependency ranges of the installed v4 release, the latest v4 release and v5 against the installed React, and upgrade in the order those ranges allow, building after each step; quote any resolver error you hit. Then run MUI's v5 preset-safe codemod and show its diff. Read the diff and the migration guide for defaults that changed but were not rewritten: at least the TextField, Select and FormControl default variant and the Link underline default; run the separate codemods for those where the app relied on the old default. If the app keeps JSS styles through @mui/styles, make sure those rules still override the library's own styles: check the order of style tags in a rendered page and add the documented provider at the root if needed. Do not rewrite withStyles to styled or sx in this pull request, do not restyle anything, and do not upgrade the build tool. Build, take the same screenshots again and compare them. Open a pull request with the upgrade order and why, each codemod's diff summary, the before and after screenshots, and a list of what remains for a later step toward current MUI.",
"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 small in lines and specific in its reasoning. package.json and the lockfile move React to 17 and replace @material-ui/core with the four new packages. The four source files change their imports, three of them gain variant="standard" on their text fields, and src/index.js gains the StyledEngineProvider wrapper. The commits follow the upgrade order, so each one builds and a bisect lands on a single step.
The description pairs every change with what would have happened without it. It quotes the resolver error that forced v4 to 4.12 before React could move. It shows the preset's diff and states what the preset did not do. It includes the screenshots of the list and add screens before and after, where the things to compare are the text fields' underline style, the bar's colour and the three coloured buttons. A reviewer who doubts the provider is needed can remove that one wrapper locally and watch the bar and the three buttons lose their colours.
The final section is a forward plan, not work done. @mui/styles exists to carry JSS through this step, and its releases stop at the 6 line while @mui/material has moved several majors past that. Going further means converting the withStyles calls to styled or the sx prop, for which MUI ships a jss-to-styled codemod. The agent also lists ListItem with the button prop in tutorials-list.component.js, which v5 deprecates in favour of ListItemButton. It names these and changes neither.
Run it on every Monday morning
A library several majors behind is best walked forward one step per week, with a person looking at screenshots between steps. Add an automation to the Project in the console with a schedule trigger, cron set to 0 9 * * 1 and your timezone. The saved prompt tells the agent to find the installed major of the UI library, take exactly one major step using that step's official codemods, and stop with before and after screenshots and the plan for the next step.
Each fire starts one run in the Project's repository. If last week's pull request is still open, the prompt should say to report that and do nothing, so the steps never stack. The automation runs as the member who last changed it.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
This upgrade fails quietly. The build is green while text fields change shape and buttons change colour, so the proof has to be visual and has to compare like with like. The agent builds the old and the new app in the same sandbox, serves each, and captures the same routes in the sandbox's browser, so the two sets of screenshots differ only by the upgrade. The install and build commands with their output are in the session's transcript for anyone who wants to see the resolver error first hand.
It also takes a tedious sequence off a developer's machine. Finding the order the peer ranges permit means several installs that rewrite node_modules and the lockfile, some of which fail, on a toolchain that needs a special flag to build at all. A run does that on a fresh checkout and returns only the commits that worked, each one building, with the failed attempts kept as evidence instead of as a broken working tree.
Frequently asked questions
Can I skip v5 and go straight to the newest MUI?
Not safely from v4. The codemods and the migration guide are written per major, and v5 is where the package names and the styling engine change. The agent takes that step alone, proves it with screenshots, and lists what the following steps need, starting with moving off @mui/styles.
Do I have to rewrite withStyles and makeStyles now?
No. @mui/styles keeps them working on v5, provided Emotion's styles are injected first so your JSS rules still win. You do have to rewrite them before moving beyond the majors that package supports. Keeping that as a separate pull request keeps this one reviewable.
Why did my text fields change to the outlined style after upgrading?
Because the default variant changed from standard to outlined in v5 and the safe preset does not add the old default for you. Running the separate variant-prop codemod writes variant="standard" on each field that did not set one, which keeps the v4 look.
Does it work if my app is still on React 16?
The agent upgrades React as part of the job, because v5 will not install on React 16. It moves v4 to its last release first when the installed one does not accept React 17, then React, then the library, building at each step so a failure points at one change.
More jobs like this: Upgrade dependencies weekly
- Migrate From mgo to the Official MongoDB Go Driver (mgo)
- Replace minimist With util.parseArgs in a Node.js CLI (minimist)
- Migrate From mitchellh/mapstructure to go-viper/mapstructure v2 (mapstructure)
- Replace the mock Backport With unittest.mock (mock)
- Migrate From mysql to mysql2 in a Node.js App (mysql (Node.js))
- Migrate from node-sass to Dart Sass in a Webpack Project (webpack)