Migrate Material-UI 4 to Mui-5

A month ago the Mui team released version 5 of Material-ui . they made some changes in this version, and some of them we'll need to configure at our own aymore. let's have a depth look over it!

prerequisite:

• first make sure to commit your code before upgradation
• Install the latest packages of react, react-dom, and react-scripts.

Installation

They rename the packages name from
@material-ui/core to @mui/material
@material-ui/lab to @mui/lab
@material-ui/icons to @mui/icons-material

and additionally we also need to install the @emotion for the style as they deprecated their styles APIS like makeStyle and move to @mui/system lib. now you either use the @emotion or styled-components.

$ yarn add @mui/material @mui/lab @mui/icons-material 
# NPM
$ npm i @mui/material @mui/lab @mui/icons-material

Installing @motion/styled

$ yarn add @mui/system @emotion/react @emotion/styled
# NPM
$ npm i @mui/system @emotion/react @emotion/styled

Installing styled-components

For the yarn user there is good news: we can simples alias the styled-components package and BOOM. to do so, add the following lines in the package.json file and run again yarn it will install the @mui/styled-engine-sc as style-engine and also install the styled-components. remove the previously installed @emtion/* style lib.

 {
   "dependencies": {
-    "@mui/styled-engine": "latest"
+    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
   },
+  "resolutions": {
+    "@mui/styled-engine": "npm:@mui/styled-engine-sc@latest"
+  },
 }

installing fonts

by default, it before gave us the robot font. now we're responsible for installing and hosting the font for yourself. there're few way to use fonts in react app, the recommended is self-hosted, so we're using @fontsource to install font:

$ yarn add @fontsource/roboto
# NPM
$ npm install @fontsource/roboto

now we need to import it to entry point like where you're wrapping ThemeProvider or either in theme.js file:

import '@fontsource/roboto/300.css';
import '@fontsource/roboto/400.css';
import '@fontsource/roboto/500.css';
import '@fontsource/roboto/700.css';

Configuration Global Theme Object

the createMuiTheme renamed to createTheme, also the structure of theme has changed in v5. adaptV4Theme helper allow you to iteratively upgrade some of theme changes to new theme structure structure. but will be removed this soon in the next version.

import { createTheme, adaptV4Theme } from '@mui/material/styles';
  const theme = createTheme(adaptV4Theme({
   // v4 theme
  });
}));

the fade renamed the alpha:

import { alpha } from '@mui/material/styles';

backgroundColor: alpha(theme.palette.primary.main, theme.palette.action.selectedOpacity),

ThemeProvider:

import { ThemeProvider, createTheme } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';

const theme = createTheme();

function App() {
ThemeProvider
  return (
    <ThemeProvider theme={theme}>
       <CssBaseline />
       <Root />
    </ThemeProvider>
  );
}

Update all codebase

as the package name renamed, definitely you need to import the new package name. to do so, now what if you have a hundred of components will you do it manually? You can surely use sed and awk for the bulk changes. but we got another support which made the migration easy. we'll be using codemod which sounds like as I said above plus more feature and some warning, which you should care of it:

$ npx @mui/codemod v5.0.0/preset-safe src/components/Button

replace the src/components/Button to your component's path and it'll rename the import package in the files. once the process done open up the file and see the import files, You should have new path imported:

- import Avatar from '@material-ui/core/Button';
+ import Avatar from '@mui/material/Button';

@mui/codemod v5.0.0/preset-safe will do all the magic for you without to worry.

Do we have makeStyles?

yes, we still have the makeStyles style API (but it's deprecated and will be removed in the next version). for that we need to install @mui/styles package:

import { createStyles, makeStyles, withStyles } from '@mui/styles';

alternative solution of this is to use the sx APIs, it support CSS project:

<Box sx={{ border: "1px dashed grey", p: [2, 3, 4], m: 2 }}>

another solution to migrate the makeStyles to styled using codemod:

$ npx @mui/codemod v5.0.0/jss-to-styled <path>

it generate new code style

-const useStyles = makeStyles((theme) => ({
-  chip: {
-    padding: theme.spacing(1, 1.5),
-    boxShadow: theme.shadows[1],
-  }
-}))

// TO THIS
+const Root = styled('div')({
+  display: 'flex',
+})

Final World

We're working on project where we were using Material-ui as the new version came out I decided to upgrade to new version and thankfully our team manager agreed. because I wanted to get most out of @mui new feature and changes. We've discuss some important topics which you need to know when doing migration. and I hope it helps you!

If you find this post helpful, please share it with family and friends, feel free to share any response on it!

twitter: https://twitter.com/xericgit

Comments

[damilola jerugba]

Nice, I personally don't like MUI, I love the fact that it has alot of components but visually it either looks too Google websity or generally unattractive. Plus it's so difficult to customize even after the new update

[Elias Júnior]

I think the same as you, but as you can see in the homepage, it's possible to have a custom theme, that makes a lot of difference. Maybe in some time we will see some good open-source/paid themes.

[HasOne]

I think we already some of paid theme availabe in the mui market, thanks!

[HasOne]

@damiisdandy I totally agree with you. but It give us ability to use our own design, thanks!

[damilola jerugba]

Yes I’m it does, just wasn’t as streamlined

[Hulya]

Hi, thanks for writing this post. I'm getting an error like this when I try to run the project.`Child process failed to process the request: Error: Debug Failure. False expression.

Did you have any problem like that? I have found this error happened in typescript's older versions but I have updated the Typescript module. Do you think this is another bug?

Similar to this: stackoverflow.com/questions/508366...

[Roman]

If someone uses breakpoints in their theme for createTheme(), then I have a solution for how to get breakpoints

Material-UI 4

import createBreakpoints from '@material-ui/core/styles/createBreakpoints'

const breakpoints = createBreakpoints({})

export const defaultTheme = {...}

Mui-5

yarn add @mui/system

import { createBreakpoints } from '@mui/system'

const breakpoints = createBreakpoints({})

export const defaultTheme = {...}

[Eric Gish]

Thank you for adding this snippet. I was trying to figure this out!

[htorohn]

I have a questions, to run the codemods, do I have to run it file by file, or if run it on the src folder it will go recursively applying the changes on all files?

[HasOne]

You can do both methods either on each file or src, components...

[abhishekdam-Borderfree]

can anyone tell me what is the script for codemod for just changing the muiv4 icons to muiv5 icons (just the icons and nothing)?

[Paras 🧙‍♂️]

Very well explained !!

[Kamal Choudhary]

thank you so much for the very helpful tutorial. One question though, I recently upgraded Material UI from 4 to 5 and all of the Dialog components show at the end of the pages - they cause the page scroll all the way to the bottom and then they display - any clue how can I solve this - thanks!

[Kamal Choudhary]

Found that my Dialog components had "position: relative" in the MUI 4 implementation and they were being shown in the right place - but in MUI 5, they work fine without adding that CSS property.

[csemorf]

good

[Josh Blengino]

So clutch, thank you!