MUI v4에서 v5로 버전 업그레이드 하기

회사의 여러 프로젝트 중 라이브러리 업데이트가 주기적으로 이루어지지 않은 프로젝트가 있는데, 그 중 하나의 프로젝트를 맡아 라이브러리 업데이트 작업을 진행했습니다.

React v18을 사용하기 위해 MUI v4에서 MUI v5로 업데이트 하는 작업을 선행했습니다.

Introduction

MUI v5의 가장 큰 차이점은 emotion을 기본 스타일링 솔루션으로 변경했다는 부분입니다.
만약 MUI v5를 styled-components와 함께 사용한다면, 그에 따른 추가적인 작업이 필요합니다.
자세한 설명은 하단에서 다루겠습니다.

Supported browsers and Node versions

라이브러리 업데이트를 진행하기 전에 꼭 확인해야하는 부분입니다.
지원하는 브라우저 및 노드 버전을 확인합니다.
또한, React v18로 업데이트를 위해 MUI를 v5로 업데이트 하는 것처럼 업그레이드 하는 라이브러리가 다른 라이브러리의 버전과 호환되는지 꼭 확인하시길 바랍니다.

• Node 12 (up from 8)
• Chrome 90 (up from 49)
• Edge 91 (up from 14)
• Firefox 78 (up from 52)
• Safari 14 (macOS) and 12.5 (iOS) (up from 10)
• .browserslistrc (stable entry)을 통해 browserlist를 확인해주세요.

Update React

React 최소 지원 버전이 v16.8.0 에서 v17.0.0로 변경되었습니다.
따라서, 현재 React의 버전이 v17 이하거나 MUI의 버전이 v4.11.2 이하라면 다음과 같은 업데이트가 필요합니다.

npm install @material-ui/core@^4.11.2 react@^17.0.0

TypeScript 최소 지원 버전 또한 v3.2 에서 v3.5 로 변경되었으므로 TypeScript를 사용 중이라면 함께 업데이트를 해주세요.
자세한 내용은 공식문서를 참고해주세요.

Set up ThemeProvider

ThemeProvider를 셋팅합니다.

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

import Root from 'pages';

const theme = createTheme();

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

export default App;

Update MUI packages

Material UI v5 패키지와 @mui/styles를 설치합니다.

npm install @mui/material @mui/styles

MUI icon도 사용 중이라 icon 패키지도 설치했습니다!

npm install @mui/icons-material

Peer dependencies

Emotion도 설치해줍니다.

npm install @emotion/react @emotion/styled

Replace all imports

v5에서 패키지 이름이 @material-ui/* 에서 @mui/* 로 변경되었습니다.

변경된 패키지 이름은 다음과 같습니다.

@material-ui/core -> @mui/material
@material-ui/unstyled -> @mui/base
@material-ui/icons -> @mui/icons-material
@material-ui/styles -> @mui/styles
@material-ui/system -> @mui/system
@material-ui/lab -> @mui/lab
@material-ui/types -> @mui/types
@material-ui/styled-engine -> @mui/styled-engine
@material-ui/styled-engine-sc ->@mui/styled-engine-sc
@material-ui/private-theming -> @mui/private-theming
@material-ui/codemod -> @mui/codemod
@material-ui/docs -> @mui/docs
@material-ui/envinfo -> @mui/envinfo

위의 이름에 맞게 import 경로를 수정합니다.

Run codemods

v5로 업그레이드로 인한 변경사항을 자동으로 적용할 수 있도록 codemod를 사용할 수 있습니다.

codemod는 한 폴더에 한 번만 적용할 수 있습니다.

npx @mui/codemod@latest v5.0.0/preset-safe <path>

codemod에 대한 자세한 내용은 다음 링크를 참고해주세요.

저는 codemod를 사용하지 않았습니다.
그 이유는 많은 변경사항을 한 번에 변경하다보면 에러가 발생했을 때 어디에서 에러가 발생했는지 찾기 어렵기 때문입니다.
실제로 eslint를 적용하고 fix 스크립트를 돌렸다가 에러가 어디에서 발생했는지 찾지 못해 시간을 허비한 경험이 있습니다.

그 이후로는 모든 변경사항을 한 번에 적용하지 않습니다.

Remove old packages

v4 패키지를 사용하는 곳이 없는 것을 확인 후 v4 패키지를 삭제합니다.

npm uninstall @material-ui/*

styled-components 와 사용하기

MUI는 emotion을 기본 스타일링 엔진으로 사용하기 때문에 styled-components 와 MUI를 사용하기 위해서는 다음 패키지들을 추가로 설치합니다.

npm install @mui/material @mui/styled-engine-sc styled-components

MUI는 Material UI와의 호환성을 위해 스타일링 솔루션을 감쌀 수 있는 두 가지 패키지를 제공합니다.

• @mui/styled-engine: 스타일의 필수 유틸리티를 포함하는 emotion의 styled() API의 wrapper 입니다.

• @mui/styled-engine-sc: @mui/styled-engine와 유사하지만 styled-components를 위한 wrapper로 styled-components를 사용하기 위해서는 필수로 설치해야합니다.

Bundler configuration

기본적으로 @mui/material 는 @mui/styled-engine 에 종속되어 있습니다.
styled-components를 사용하기 위해 번들러의 설정을 @mui/styled-engine-sc로 변경해야합니다.

With yarn

yarn을 사용한다면 다음과 같이 package.json 설정을 해줍니다.

 // package.json

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

With npm

npm은 yarn과 같은 package resolutions 을 사용할 수 없습니다.
따라서, 웹팩을 이용한 설정이 필요합니다.

 // webpack.config.js

 module.exports = {
   //...
+  resolve: {
+    alias: {
+      '@mui/styled-engine': '@mui/styled-engine-sc'
+    },
+  },
 };

TypeScript를 사용한다면 tsconfig.json을 다음과 같이 수정해야합니다.

 // tsconfig.json

 {
   "compilerOptions": {
+    "paths": {
+      "@mui/styled-engine": ["./node_modules/@mui/styled-engine-sc"]
+    }
   },
 }

Emotion 사용하기

기존 프로젝트에서는 styled-components와 MUI를 함께 사용하고 있었습니다.
그래서 동일하게 사용하기 위해 위의 추가 설정을 하려고 했으나 styled-components를 삭제하고 emotion을 이용하기로 결정했습니다.

그 이유는 다음과 같습니다.

• styled-components를 꼭 사용해야할 이유가 없다.
• styled-components를 사용하기 위해 웹팩을 설치해야한다.
• emotion을 사용하는데 불편함이 없다.

그래서 styled-components 코드를 emotion으로 변경 후 styled-components를 삭제했습니다.

참고

• Migrating to v5: getting started
• Using styled-components