Migrating to v5: getting started

Migrating to v5: getting started (v5로 마이그레이션: 시작하기)

이 가이드는 Material UI v4에서 v5로 어떻게, 그리고 왜 마이그레이션해야 하는지 설명해요.

출처: 문서

본문

Material UI v5 마이그레이션

  1. Getting started 👈 당신은 여기
  2. Breaking changes part one: style and theme
  3. Breaking changes part two: components
  4. Migrating from JSS
  5. Troubleshooting

소개 (Introduction)

이 문서는 앱을 Material UI v4에서 v5로 업그레이드하도록 안내하는 다중 시리즈의 첫 번째 문서예요.

효율성을 위해 codemods를 실행하는 것을 강력히 권장해요. 이들은 v5에서 도입된 많은 breaking changes를 자동으로 처리해 줄 거예요.

v5에서 가장 큰 변경 중 하나는 기본 스타일링 솔루션으로 JSS를 Emotion으로 교체한 것이에요.

v5로 마이그레이션한 후에도 컴포넌트에 오버라이드를 추가하기 위해 JSS(예를 들어 makeStyles, withStyles)를 계속 사용할 수 있다는 점을 알아두세요. 나머지 v5 업그레이드를 완료한 후에는 점진적으로 새 스타일링 엔진으로 전환하는 것을 권장해요.

이 과정은 Migrating from JSS에서 다룹니다.

:::info 이전 버전의 문서를 다시 참조해야 하나요? v4 문서는 여기에서 확인하세요. :::

:::info Next.js를 사용하고 있고 Emotion과 JSS 모두에서 SSR을 구성하는 방법을 잘 모르겠다면, 이 예제 프로젝트를 살펴보세요. :::

왜 마이그레이션해야 하나요

Material UI v5에는 v4보다 많은 버그 수정과 개선이 포함되어 있어요.

이러한 개선 중 가장 중요한 것은 새로운 스타일링 엔진인데, 동적 스타일에 관한 성능에서 상당한 발전을 제공하고, 더 즐거운 개발자 경험을 제공해요.

추가로, v5는 React 18을 완전히 지원하는 유일한 버전이므로, 최신 React 기능을 활용하려면 마이그레이션해야 해요.

더 알아보려면 Material UI v5 출시에 관한 블로그 포스트를 확인하세요.

:::success 진행하면서 작은 커밋을 만들어 부드러운 마이그레이션을 보장하세요.

도중에 문제가 발생하면 Troubleshooting 문서를 확인하세요.

여기서 다루지 않는 문제는 [Migration] 문제 요약 형식의 제목으로 이슈를 만들어 주세요. :::

지원되는 브라우저와 Node 버전

v5에서 기본 번들의 대상이 변경되었어요.

정확한 버전은 릴리스 시 browserslist 쿼리 "> 0.5%, last 2 versions, Firefox ESR, not dead, not IE 11, maintained node versions"에서 고정될 거예요.

기본 번들은 다음 최소 버전을 지원해요:

  • Node 12 (8에서 상향)
  • Chrome 90 (49에서 상향)
  • Edge 91 (14에서 상향)
  • Firefox 78 (52에서 상향)
  • Safari 14 (macOS) 및 12.5 (iOS) (10에서 상향)
  • 그리고 더 많은 것 (참고: .browserslistrc (stable entry))

Material UI는 더 이상 IE 11을 지원하지 않아요. IE 11을 지원해야 한다면, legacy bundle을 확인하세요.

React 및 TypeScript 버전 업데이트

React 업데이트

지원되는 최소 React 버전이 v16.8.0에서 v17.0.0으로 상향되었어요.

React 17.0.0 미만 버전을 사용 중이라면, Material UI를 적어도 v4.11.2로, React를 v17.0.0으로 패키지를 업데이트하세요.

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

yarn upgrade @material-ui/core@^4.11.2 react@^17.0.0

TypeScript 업데이트

지원되는 최소 TypeScript 버전이 v3.2에서 v3.5로 상향되었어요.

:::info 우리는 DefinitelyTyped에서 릴리스하는 타입(@types 네임스페이스 아래에 npm에 게시되는 패키지들)과 맞추려고 노력해요.

Material UI의 마이너 버전에서는 지원되는 최소 버전을 변경하지 않을 거예요. 하지만 일반적으로 DefinitelyTyped의 최저 지원 버전보다 오래된 TypeScript 버전을 사용하지 않는 것을 권장해요. :::

프로젝트에 다음 패키지가 포함되어 있다면 업데이트해야 해요:

  • react-scripts
  • @types/react
  • @types/react-dom

:::warning 애플리케이션이 여전히 오류 없이 실행되는지 확인하고, 다음 단계로 진행하기 전에 변경 사항을 커밋하세요. :::

ThemeProvider 설정

v5로 업그레이드하기 전에, 기본 테마를 사용하더라도 애플리케이션의 루트와 테스트에 ThemeProvider가 정의되어 있고, useStyles가 ThemeProvider 전에 호출되지 않는지 확인하세요.

결국엔 JSS에서 Emotion으로 마이그레이션하고 싶을 거예요. 하지만 그 동안은 deprecated된 @mui/styles 패키지로 이전 JSS 기반 유틸리티를 계속 사용할 수 있어요. 이 패키지는 ThemeProvider를 필요로 해요.

애플리케이션의 루트는 대략 이렇게 생겨야 해요:

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

const theme = createMuiTheme();

const useStyles = makeStyles((theme) => {
  root: {
    // some CSS that accesses the theme
  }
});

function App() {
  const classes = useStyles(); // ❌ If you have this, consider moving it
  // inside of a component wrapped with <ThemeProvider />
  return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
}

:::warning 애플리케이션이 여전히 오류 없이 실행되는지 확인하고, 다음 단계로 진행하기 전에 변경 사항을 커밋하세요. :::

Material UI 패키지 업데이트

Material UI v5 및 @mui/styles

Material UI v5 패키지를 설치하세요.

```bash npm npm install @mui/material @mui/styles ``` 
yarn add @mui/material @mui/styles

@material-ui/lab 또는 @material-ui/icons를 사용 중이라면, 새 패키지를 설치해야 해요.

@material-ui/lab

```bash npm npm install @mui/lab ``` 
yarn add @mui/lab

@material-ui/icons

```bash npm npm install @mui/icons-material ``` 
yarn add @mui/icons-material

날짜 및 시간 피커

날짜 및 시간 피커 컴포넌트는 MUI X로 이동했어요. @material-ui/date-pickers 또는 @mui/lab 패키지의 피커를 사용 중이라면, @mui/x-date-pickers로 마이그레이션해야 해요. 자세한 내용은 lab에서 마이그레이션을 참고하세요.

Peer dependencies

다음으로 Emotion 패키지를 추가하세요.

npm install @emotion/react @emotion/styled

yarn add @emotion/react @emotion/styled

styled-components (선택 사항)

Emotion 대신 styled-components와 함께 Material UI v5를 사용하고 싶다면, Material UI 설치 가이드를 확인하세요.

앱이 서버 사이드 렌더링(SSR)을 사용한다면, styled-components용 Babel 플러그인에 @mui/styled-engine-sc(styled-components용 어댑터)를 사용할 수 없게 하는 알려진 버그가 있다는 점을 알아두세요.

Emotion과 함께 기본 설정을 사용하는 것을 강력히 권장해요.

:::warning 애플리케이션이 여전히 오류 없이 실행되는지 확인하고, 다음 단계로 진행하기 전에 변경 사항을 커밋하세요. :::

모든 import 교체

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/internal-core-docs
@material-ui/envinfo -> @mui/envinfo

이전 패키지 제거

필요한 모든 패키지를 설치하고 앱이 여전히 실행되는지 확인한 후에는, npm uninstall @material-ui/* 또는 yarn remove @material-ui/*를 실행해서 이전 @material-ui/* 패키지를 안전하게 제거할 수 있어요.

:::success preset-safe codemod(아래에서 자세히 설명)가 이를 자동으로 처리해요. :::

CSS 특이성(specificity) 수정 (선택 사항)

CSS 파일을 import해서 컴포넌트에 스타일을 적용하려면, 올바른 컴포넌트를 대상으로 지정할 수 있도록 특이성을 높여야 해요.

다음 예시를 고려해 보세요:

import './style.css';
import Chip from '@mui/material/Chip';

const ChipWithGreenIcon = () => (
  <Chip
    classes={{ deleteIcon: 'green' }}
    label="delete icon is green"
    onDelete={() => {}}
  />
);

이 예시에서 Chip의 delete icon에 특정 스타일을 올바르게 적용하려면, 아래와 같이 CSS 클래스의 특이성을 높이는 것이 한 가지 옵션이에요:

.MuiChip-root .green {
  color: green;
}

대조적으로, 다음 CSS 스니펫은 delete icon에 스타일을 적용하지 않아요:

.green {
  color: green;
}

codemods 실행

다음 codemods는 v5의 breaking changes를 처리하도록 코드의 대부분을 자동으로 조정할 거예요.

각 codemod를 실행한 후에도 애플리케이션이 오류 없이 실행되는지 확인하고, 다음 단계로 진행하기 전에 변경 사항을 커밋하세요.

preset-safe

이 codemod는 마이그레이션에 필요한 대부분의 트랜스포머를 포함해요. 폴더당 한 번만 적용해야 해요.

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

:::info 트랜스포머를 하나씩 실행하고 싶다면, 더 자세한 내용은 preset-safe codemod를 참고하세요. :::

variant-prop

이 codemod는 <TextField/>, <FormControl/>, <Select/> 컴포넌트를 변환하는데, variant가 정의되지 않았다면 variant="standard"를 적용해요 — 기본 variant가 v4의 "standard"에서 v5의 "outlined"로 변경되었어요.

:::error 테마의 기본값으로 이미 variant: "outlined"을 정의했다면 이 codemod를 사용하면 안 됩니다. :::

// ❌ if you have a theme setup like this, don't run this codemod.
// these default props can be removed later because `outlined` is the default value in v5
createMuiTheme({
  components: {
    MuiTextField: {
      defaultProps: {
        variant: 'outlined',
      },
    },
  },
});

컴포넌트에서 variant="standard"를 유지하려면 이 codemod를 실행하거나 해당하는 기본 테마 props를 구성하세요.

npx @mui/codemod@latest v5.0.0/variant-prop <path>

더 자세한 내용은 variant-prop codemod README를 확인하세요.

이 codemod는 underline prop이 정의되지 않았다면 underline="hover"를 적용해 <Link /> 컴포넌트를 변환해요 — 기본 underline이 v4의 "hover"에서 v5의 "always"로 변경되었어요.

:::error 테마의 기본값으로 이미 underline: "always"를 정의했다면 이 codemod를 사용하면 안 됩니다. :::

// if you have theme setup like this, ❌ don't run this codemod.
// this default props can be removed later because `always` is the default value in v5
createMuiTheme({
  components: {
    MuiLink: {
      defaultProps: {
        underline: 'always',
      },
    },
  },
});

underline="hover"를 유지하려면 이 codemod를 실행하거나 해당하는 기본 테마 props를 구성하세요.

npx @mui/codemod@latest v5.0.0/link-underline-hover <path>

더 자세한 내용은 link-underline-hover codemod README를 확인하세요.

breaking changes 처리

codemods는 많은 breaking changes를 처리하지만, 그 외의 것은 수동으로 처리해야 해요.

codemods를 사용하든 말든, 이제 breaking changes 문서 두 개 중 첫 번째로 넘어갈 준비가 됐어요.

더 알아보기 (Learn more)