Installation

Installation (설치)

세계에서 가장 인기 있는 React UI 프레임워크인 Material UI를 설치해봐요.

출처: 문서

본문

Default installation (기본 설치)

프로젝트에 Material UI를 추가하려면 다음 명령 중 하나를 실행해요:

npm install @mui/material @emotion/react @emotion/styled

pnpm add @mui/material @emotion/react @emotion/styled

yarn add @mui/material @emotion/react @emotion/styled

Peer dependencies (피어 의존성)

react와 react-dom은 피어 의존성(peer dependencies)이라는 점을 기억하세요. 즉 Material UI를 설치하기 전에 이들이 설치되어 있는지 확인해야 해요.

"peerDependencies": {
  "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
  "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
},

React 18 and below (React 18 이하)

React 18 이하를 사용하고 있다면, 사용 중인 react 버전과 같은 버전으로 react-is 패키지의 resolution을 설정해야 해요.

예를 들어 [email protected]을 사용한다면, 다음 단계를 따르면 돼요:

  1. [email protected]을 설치해요.
npm install [email protected]

pnpm add [email protected]

yarn add [email protected]
  1. package.json에 resolutions 또는 overrides를 설정해요.
{
  …
  "overrides": {
    "react-is": "^18.3.1"
  }
}

{
  …
  "overrides": {
    "react-is": "^18.3.1"
  }
}

{
  …
  "resolutions": {
    "react-is": "^18.3.1"
  }
}

Why is this needed? (왜 이게 필요한가요?)

Material UI는 react-is@19를 사용하는데, 이는 React 요소를 식별하는 방식을 변경했어요.

React 18 이하를 사용 중이라면, react-is 버전이 맞지 않으면 prop 타입 검사에서 런타임 오류가 발생할 수 있어요. react-is를 React 버전에 맞추면 이런 오류를 방지할 수 있어요.

With styled-components

Material UI는 기본 스타일링 엔진으로 Emotion을 사용해요. 대신 styled-components를 사용하고 싶다면, 다음 명령 중 하나를 실행해요:

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

pnpm add @mui/material @mui/styled-engine-sc styled-components

yarn add @mui/material @mui/styled-engine-sc styled-components

다음으로, styled-components 사용 가이드를 따라 번들러가 @mui/styled-engine-sc를 지원하도록 제대로 구성해요.

:::error 2021년 말 기준으로, styled-components는 서버 렌더링(server-rendered) Material UI 프로젝트와 호환되지 않아요. babel-plugin-styled-components가 @mui 패키지 내부의 styled() 유틸리티와 함께 동작할 수 없기 때문이에요. 자세한 내용은 이 GitHub 이슈를 참고하세요.

SSR 프로젝트에서는 Emotion을 사용하는 것을 강력히 권장해요. :::

Roboto font (Roboto 폰트)

Material UI는 기본적으로 Roboto 폰트를 사용해요. Fontsource를 통해 또는 Google Fonts CDN으로 프로젝트에 추가해요.

npm install @fontsource/roboto

pnpm add @fontsource/roboto

yarn add @fontsource/roboto

그런 다음 엔트리 포인트에서 다음과 같이 import할 수 있어요:

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

:::info Fontsource는 특정 서브셋(subset), weight, 스타일만 불러오도록 구성할 수 있어요. Material UI의 기본 타이포그래피 설정은 300, 400, 500, 700 폰트 weight에만 의존해요. :::

Google Web Fonts (구글 웹 폰트)

Google Web Fonts CDN을 통해 Roboto를 설치하려면, 프로젝트의 <head /> 태그 안에 다음 코드를 추가해요:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap"
/>

Icons (아이콘)

폰트 아이콘 컴포넌트나 사전 빌드된 SVG Material Icons(예: 아이콘 데모에 있는 것들)를 사용하려면, 먼저 Material Icons 폰트를 설치해야 해요. npm 또는 Google Web Fonts CDN으로 설치할 수 있어요.

npm install @mui/icons-material

pnpm add @mui/icons-material

yarn add @mui/icons-material

Google Web Fonts (구글 웹 폰트)

Google Web Fonts CDN을 사용해 프로젝트에 Material Icons 폰트를 설치하려면, 프로젝트의 <head /> 태그 안에 다음 코드 조각을 추가해요.

폰트 Icon 컴포넌트를 사용하려면 먼저 Material Icons 폰트를 추가해야 해요. 방법에 대한 몇 가지 안내가 있으니 참고하세요. 예를 들어 Google Web Fonts를 통해서는 다음과 같이 해요:

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/icon?family=Material+Icons"
/>

CDN

가벼운 프런트엔드 인프라만으로 Material UI를 바로 사용하기 시작할 수 있는데, CDN을 통해 설치하면 됩니다. 빠른 프로토타이핑에 좋은 선택이에요.

시작하려면 이 CDN 예제를 따라 해보세요.

:::error 이 방법은 프로덕션에서 사용하는 것을 권장하지 않아요. 실제로 사용하는 컴포넌트와 관계없이 클라이언트가 전체 라이브러리를 다운로드해야 하므로, 성능과 대역폭 사용에 부정적인 영향을 미치기 때문이에요. :::

더 알아보기 (Learn more)