Migrate React Apps from Material-UI (MUI) v4 to v5: A Step-by-Step Guide

Let’s be real, running an npm run build and seeing a wall of red deprecation warnings is a total vibe killer. If your React app is still rocking Material-UI (MUI) v4, your codebase is officially giving legacy. MUI v5 is where it’s at, bringing massive performance gains, the highly flexible sx prop, and a modernized styling engine powered by Emotion. But moving a production app away from JSS (makeStyles) without breaking your entire UI? That can feel like a canon event.

No capping, migrating doesn't have to be a nightmare. If you want to level up your stack and keep your codebase clean, this comprehensive checklist and step-by-step guide will ensure a smooth upgrade with zero stress.

Material-UI (MUI) v5 brought incredible updates, including better performance, a modernized custom styling engine powered by Emotion, and the highly flexible sx prop. However, migrating a production application from v4 to v5 can be daunting because the underlying style engine moved away from JSS (makeStyles, withStyles).

Prerequisites Before Migration

Before initiating the upgrade process, ensure that your application meets the minimum dependency requirements:

React Version: Your application must be running on React 17 or React 18.
TypeScript Version: If your codebase uses TypeScript, ensure it is upgraded to v3.5 or higher.
Stable Build: Ensure your existing v4 codebase compiles perfectly with zero active build errors or console warnings.

Step 1: Install New v5 Core Packages & Peer Dependencies

MUI v5 introduces a completely new npm scoping namespace. Packages have changed from @material-ui/core to @mui/material. Since Emotion is now the default style engine, you must install it alongside the core components.

Run the following command in your project terminal:

# Using npm
npm install @mui/material @emotion/react @emotion/styled @mui/icons-material

# Using yarn
yarn add @mui/material @emotion/react @emotion/styled @mui/icons-material

Note: If you plan to temporarily keep your legacy JSS structures (makeStyles) intact during the migration phase, also run npm install @mui/styles.

Step 2: Leverage Automated Codemods

Manually updating imports across hundreds of files is highly inefficient. The MUI team provides an official suite of automated script runners (codemods) that will handle approximately 80% of the breaking syntax changes for you.

Run the preset-safe codemod script at the root directory of your project:

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

What this automated script fixes in your codebase:

Automatically shifts package import declarations from @material-ui/core/* to @mui/material/*.
Migrates component packages that moved from the Lab ecosystem into the Core ecosystem (e.g., Autocomplete, Alert, Pagination).
Renames internal utility functions automatically, such as changing createMuiTheme to createTheme.

Step 3: Update the Theme Schema Configuration

One of the biggest breaking structural changes in v5 is how custom themes are declared inside the createTheme configuration object. The older v4 target properties props and overrides have been consolidated inside a unified components key.

Review the structural transformation below:

Legacy v4 Theme Structure:

import { createMuiTheme } from '@material-ui/core/styles';

const theme = createMuiTheme({
  props: {
    MuiButton: {
      disableRipple: true,
    },
  },
  overrides: {
    MuiButton: {
      root: {
        textTransform: 'none',
      },
    },
  },
});

Modern v5 Theme Structure:

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

const theme = createTheme({
  components: {
    MuiButton: {
      defaultProps: {
        disableRipple: true,
      },
      styleOverrides: {
        root: {
          textTransform: 'none',
        },
      },
    },
  },
});

Crucial Troubleshooting Pitfalls to Avoid

Even after running the automated codemods, keep a close eye out for these frequent integration issues:

CSS Specificity & Injection Order: Emotion dynamically injects styles at the very bottom of the HTML <head> tag. If your application relies on custom global CSS or external libraries like Tailwind CSS, MUI's styles might override them. To resolve this, wrap your application in a custom Emotion CacheProvider configured with prepend: true.
JSS StrictMode Warnings: While installing @mui/styles lets you keep using legacy makeStyles hooks, this legacy syntax is fundamentally incompatible with React 18's StrictMode. Treat this as a temporary bridge and plan a secondary phase to swap old hooks over to the modern sx prop or styled components.
Color Default Fallbacks: Components like AppBar or Button may feature subtle default background color shifts depending on whether your theme palette specifies an explicit default or paper background mode.

Key Takeaways

Migrating your React UI layer to MUI v5 unlocks significant performance optimizations, a cleaner styling workflow via the sx prop, and direct compatibility with newer React features. By leveraging the automated preset-safe codemod and updating your central theme configuration file first, you can execute a smooth upgrade without ground-up rewriting.

Android App