CSS Modules 완벽 가이드

TUTORIAL

CSS Modules 완벽 가이드

CSS 스코핑과 모듈화로 스타일 충돌 없는 컴포넌트 개발. composes, :global, 동적 클래스 활용법을 배웁니다.

럿지 AI 팀

2025-01-12

15분

CSS Modules란?

CSS를 모듈 단위로 스코핑하여
클래스 이름 충돌 없이 스타일을 관리합니다.

/* Button.module.css */
.button {
  background: #6366f1;
  padding: 8px 16px;
}

.primary {
  composes: button;
  background: #8b5cf6;
}

/* 컴파일 결과 */
.Button_button__x7f2d { ... }
.Button_primary__a3k9j { ... }

왜 CSS Modules인가?

스코프 격리

자동 해시로 클래스 이름 충돌 방지

컴포넌트 연동

JS에서 직접 import하여 사용

composability

composes로 스타일 상속 가능

빌드 최적화

사용된 스타일만 번들에 포함

사용 방법

1. CSS 파일 생성

/* Card.module.css */
.card { border-radius: 8px; }
.title { font-size: 1.25rem; }

2. 컴포넌트에서 import

import styles from './Card.module.css';

function Card() {
  return (
    <div className={styles.card}>
      <h2 className={styles.title}>제목</h2>
    </div>
  );
}

고급 기능

:global() - 전역 스타일

:global(.dark-mode) .button {
  background: #1f2937;
}

composes - 스타일 상속

.primaryBtn {
  composes: button;
  composes: primary from './colors.module.css';
}

동적 클래스

className={clsx(styles.btn, {
  [styles.active]: isActive,
  [styles.disabled]: isDisabled
})}

CSS 방법론 비교

방법론	스코핑	런타임
CSS Modules	자동	없음
BEM	수동	없음
styled-components	자동	있음
Tailwind	유틸리티	없음