Material UI 트러블슈팅 완벽 가이드

Material UI 사용 시 자주 발생하는 문제들과 해결 방법을 다룹니다. 테마 커스터마이징, 스타일링 충돌, 성능 최적화 등 실무에서 바로 적용 가능한 솔루션을 제공합니다.

---

---

들어가며

이 글에서는 Material UI 트러블슈팅 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. Theme_Provider_누락_에러
2. CSS_우선순위_충돌_해결
3. SSR_하이드레이션_불일치
4. 커스텀_테마_타입_에러
5. 글로벌_스타일_덮어쓰기
6. 동적_테마_전환_최적화
7. styled_컴포넌트_Props_전달
8. 반응형_breakpoints_활용
9. Typography_variant_확장
10. 컴포넌트_기본값_오버라이드
11. emotion_캐시_purge_처리
12. createTheme_다중_병합

---

1. Theme_Provider_누락_에러

개요

"useTheme" 또는 "styled" 사용 시 ThemeProvider가 없어서 발생하는 에러를 해결하는 방법입니다.

코드 예제

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

const theme = createTheme();

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

### 설명

모든 MUI 컴포넌트를 ThemeProvider로 감싸서 테마 컨텍스트를 제공해야 합니다. 이를 통해 테마 관련 hooks와 스타일링이 정상 작동합니다.

---

## 2. CSS_우선순위_충돌_해결

### 개요

전역 CSS와 MUI 스타일이 충돌할 때 sx prop을 사용하여 우선순위를 확보하는 방법입니다.

### 코드 예제

```typescript
```typescript
import { Box } from '@mui/material';

function Component() {
  return (
    <Box sx={{
      color: 'primary.main',
      '&:hover': { bgcolor: 'action.hover' },
      '& .child': { fontSize: 14 }
    }}>
      Content
    </Box>
  );
}

### 설명

sx prop은 가장 높은 CSS 우선순위를 가지며, 테마 값에 직접 접근할 수 있어 일관성 있는 스타일링이 가능합니다.

---

## 3. SSR_하이드레이션_불일치

### 개요

Next.js나 SSR 환경에서 스타일 불일치 문제를 해결하기 위한 설정입니다.

### 코드 예제

```typescript
```typescript
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';

const cache = createCache({ key: 'css', prepend: true });

function MyApp({ Component, pageProps }) {
  return (
    <CacheProvider value={cache}>
      <Component {...pageProps} />
    </CacheProvider>
  );
}

### 설명

Emotion 캐시를 설정하여 SSR과 클라이언트 스타일이 일치하도록 보장합니다. prepend 옵션으로 MUI 스타일을 먼저 주입합니다.

---

## 4. 커스텀_테마_타입_에러

### 개요

TypeScript에서 커스텀 테마 속성을 추가할 때 타입 에러를 방지하는 방법입니다.

### 코드 예제

```typescript
```typescript
declare module '@mui/material/styles' {
  interface Theme {
    custom: {
      spacing: number;
    };
  }
  interface ThemeOptions {
    custom?: {
      spacing?: number;
    };
  }
}

### 설명

모듈 선언을 확장하여 커스텀 테마 속성의 타입을 정의합니다. 이를 통해 타입 안정성을 확보할 수 있습니다.

---

## 5. 글로벌_스타일_덮어쓰기

### 개요

CssBaseline과 함께 글로벌 스타일을 안전하게 적용하는 방법입니다.

### 코드 예제

```typescript
```typescript
import { GlobalStyles, CssBaseline } from '@mui/material';

const globalStyles = (
  <GlobalStyles styles={{
    '*': { boxSizing: 'border-box' },
    body: { margin: 0, padding: 0 },
    a: { textDecoration: 'none' }
  }} />
);

function App() {
  return <>{globalStyles}<CssBaseline /><Content /></>;
}

### 설명

GlobalStyles 컴포넌트를 사용하여 MUI와 호환되는 방식으로 글로벌 스타일을 정의합니다. CssBaseline과 함께 사용하면 브라우저 기본 스타일이 초기화됩니다.

---

## 6. 동적_테마_전환_최적화

### 개요

다크모드 전환 시 깜빡임 없이 부드럽게 테마를 변경하는 방법입니다.

### 코드 예제

```typescript
```typescript
import { useMemo } from 'react';
import { createTheme, ThemeProvider } from '@mui/material';

function App() {
  const [mode, setMode] = useState<'light' | 'dark'>('light');

  const theme = useMemo(
    () => createTheme({ palette: { mode } }),
    [mode]
  );

  return <ThemeProvider theme={theme}>...</ThemeProvider>;
}

### 설명

useMemo를 사용하여 테마 객체를 메모이제이션하면 불필요한 재생성을 방지하고 성능을 최적화할 수 있습니다.

---

## 7. styled_컴포넌트_Props_전달

### 개요

styled 컴포넌트에서 transient props를 사용하여 DOM 경고를 제거하는 방법입니다.

### 코드 예제

```typescript
```typescript
import { styled } from '@mui/material/styles';
import { Box } from '@mui/material';

const StyledBox = styled(Box, {
  shouldForwardProp: (prop) => prop !== 'isActive'
})<{ isActive: boolean }>(({ theme, isActive }) => ({
  color: isActive ? theme.palette.primary.main : 'inherit'
}));

### 설명

shouldForwardProp 옵션으로 DOM에 전달되지 않아야 할 props를 필터링합니다. 이를 통해 콘솔 경고를 방지할 수 있습니다.

---

## 8. 반응형_breakpoints_활용

### 개요

테마의 breakpoints를 사용하여 반응형 스타일을 일관성 있게 적용하는 방법입니다.

### 코드 예제

```typescript
```typescript
import { Box } from '@mui/material';

function ResponsiveComponent() {
  return (
    <Box sx={{
      width: { xs: '100%', sm: '80%', md: '60%' },
      padding: { xs: 2, md: 4 },
      fontSize: { xs: 14, sm: 16, md: 18 }
    }}>
      Responsive Content
    </Box>
  );
}

### 설명

sx prop에서 객체 형태로 breakpoint별 값을 지정하면 반응형 스타일을 간결하게 작성할 수 있습니다.

---

## 9. Typography_variant_확장

### 개요

커스텀 Typography variant를 추가하여 일관된 텍스트 스타일을 적용하는 방법입니다.

### 코드 예제

```typescript
```typescript
const theme = createTheme({
  typography: {
    poster: {
      fontSize: '4rem',
      fontWeight: 700,
      lineHeight: 1.2
    }
  }
});

declare module '@mui/material/styles' {
  interface TypographyVariants {
    poster: React.CSSProperties;
  }
}

### 설명

테마에 커스텀 variant를 정의하고 타입을 확장하면 프로젝트 전체에서 재사용 가능한 텍스트 스타일을 만들 수 있습니다.

---

## 10. 컴포넌트_기본값_오버라이드

### 개요

특정 MUI 컴포넌트의 기본 props와 스타일을 전역적으로 변경하는 방법입니다.

### 코드 예제

```typescript
```typescript
const theme = createTheme({
  components: {
    MuiButton: {
      defaultProps: { variant: 'contained' },
      styleOverrides: {
        root: { borderRadius: 8, textTransform: 'none' }
      }
    }
  }
});

### 설명

테마의 components 설정으로 모든 Button의 기본 variant와 스타일을 변경할 수 있어 코드 중복을 줄이고 일관성을 유지할 수 있습니다.

---

## 11. emotion_캐시_purge_처리

### 개요

동적 스타일 생성 시 메모리 누수를 방지하기 위한 캐시 정리 방법입니다.

### 코드 예제

```typescript
```typescript
import createCache from '@emotion/cache';

const cache = createCache({ key: 'mui' });

// 캐시 정리가 필요한 시점
function clearCache() {
  cache.sheet.flush();
  cache.inserted = {};
  cache.registered = {};
}

### 설명

대량의 동적 스타일을 생성하는 경우 캐시를 주기적으로 정리하여 메모리 사용을 최적화할 수 있습니다.

---

## 12. createTheme_다중_병합

### 개요

여러 테마 설정을 계층적으로 병합하여 모듈화된 테마를 구성하는 방법입니다.

### 코드 예제

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

const baseTheme = createTheme({ palette: { mode: 'dark' } });

const theme = createTheme(baseTheme, {
  typography: { fontFamily: 'Pretendard' },
  components: { MuiButton: { defaultProps: { size: 'large' } } }
});

### 설명

createTheme을 여러 번 호출하여 테마를 점진적으로 확장할 수 있습니다. 이를 통해 기본 테마와 프로젝트별 설정을 분리할 수 있습니다.

---

## 마치며

이번 글에서는 Material UI 트러블슈팅 완벽 가이드에 대해 알아보았습니다.
총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

### 관련 태그

#React #MaterialUI #Styling #Theme #Troubleshooting