React에서 CSS 모듈 사용하기

 

React로 프로젝트를 개발하다 보면 CSS 클래스 이름 충돌 문제를 경험할 수 있습니다. 특히, 여러 컴포넌트가 서로 다른 개발자가 작업한 CSS를 공유하거나, 공통 클래스 이름을 사용할 때 이런 문제가 발생합니다. 이를 해결하기 위해 React는 CSS 모듈이라는 강력한 스타일링 방식을 제공합니다. 이 블로그에서는 CSS 모듈의 기본 개념과 활용 방법, 그리고 실전 예제를 상세히 소개합니다.

---

CSS 모듈이란?

CSS 모듈(CSS Modules)은 각 CSS 파일이 독립적인 네임스페이스를 가지는 방식입니다. 기본적으로 파일 내 클래스 이름이 로컬 스코프(Local Scope)로 처리되며, 전역 스코프 문제를 방지합니다. 이를 통해 컴포넌트 단위로 깔끔한 스타일링이 가능합니다.

CSS 모듈의 주요 특징

• 로컬 스코프: 클래스 이름이 고유한 해시 값으로 변환됩니다.
• 재사용성: 컴포넌트 단위로 스타일을 관리할 수 있습니다.
• 충돌 방지: 글로벌 클래스 이름 충돌 없이 스타일링이 가능합니다.

---

CSS 모듈 설정하기

React 프로젝트에서 CSS 모듈을 사용하는 방법은 매우 간단합니다. Create React App으로 생성한 프로젝트는 기본적으로 CSS 모듈을 지원합니다. CSS 파일 이름에 .module.css 확장자를 사용하면 됩니다.

프로젝트 생성 및 기본 설정

npx create-react-app css-modules-demo
cd css-modules-demo

CSS 모듈 파일 생성

1. CSS 파일을 생성하며 .module.css 확장자를 사용합니다.
2. /* styles/Button.module.css */ .primaryButton { background-color: #007bff; color: white; border: none; padding: 10px 20px; border-radius: 5px; cursor: pointer; } .secondaryButton { background-color: #6c757d; color: white; border: none; padding: 10px 20px; border-radius: 5px; cursor: pointer; }
3. 컴포넌트에서 스타일을 적용합니다.
4. import React from 'react'; import styles from './styles/Button.module.css'; function Button({ type, label }) { const buttonClass = type === 'primary' ? styles.primaryButton : styles.secondaryButton; return <button className={buttonClass}>{label}</button>; } export default Button;

---

CSS 모듈 활용 예제

1. 기본 예제: 클래스 이름 사용

CSS 모듈은 기본적으로 객체로 가져와 사용할 수 있습니다.

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

function Card() {
  return (
    <div className={styles.card}>
      <h1 className={styles.title}>CSS 모듈로 스타일링하기</h1>
      <p className={styles.description}>
        CSS 모듈은 클래스 이름 충돌을 방지합니다.
      </p>
    </div>
  );
}

export default Card;

Card.module.css

.card {
  border: 1px solid #ddd;
  border-radius: 10px;
  padding: 20px;
  box-shadow: 2px 2px 10px rgba(0, 0, 0, 0.1);
}

.title {
  font-size: 1.5rem;
  color: #333;
}

.description {
  font-size: 1rem;
  color: #555;
}

---

2. 동적 클래스 조합

조건에 따라 클래스를 조합하여 사용할 수 있습니다.

import React from 'react';
import styles from './styles/Alert.module.css';

function Alert({ type, message }) {
  const alertClass =
    type === 'success'
      ? styles.success
      : type === 'error'
      ? styles.error
      : styles.info;

  return <div className={alertClass}>{message}</div>;
}

export default Alert;

Alert.module.css

.success {
  background-color: #d4edda;
  color: #155724;
  padding: 10px;
  border: 1px solid #c3e6cb;
  border-radius: 5px;
}

.error {
  background-color: #f8d7da;
  color: #721c24;
  padding: 10px;
  border: 1px solid #f5c6cb;
  border-radius: 5px;
}

.info {
  background-color: #d1ecf1;
  color: #0c5460;
  padding: 10px;
  border: 1px solid #bee5eb;
  border-radius: 5px;
}

---

3. 전역 스타일 적용

CSS 모듈은 기본적으로 로컬 스코프를 사용하지만, 전역 스타일이 필요하다면 :global을 활용할 수 있습니다.

GlobalStyles.module.css

:global(.app-container) {
  margin: 0;
  padding: 0;
  font-family: Arial, sans-serif;
}

App.js

import React from 'react';
import './styles/GlobalStyles.module.css';

function App() {
  return (
    <div className="app-container">
      <h1>전역 스타일과 CSS 모듈</h1>
    </div>
  );
}

export default App;

---

CSS 모듈과 다른 스타일링 도구 비교

특징 CSS 모듈 Styled-Components 일반 CSS

네임스페이스 충돌 방지	✅ 고유 해시 생성	✅ 동적 클래스 생성	❌ 충돌 가능
동적 스타일링	제한적(classnames 필요)	✅ 지원	❌
전역 스타일 적용	가능(:global 사용)	가능	✅ 기본적으로 전역
파일 크기	상대적으로 작음	상대적으로 큼	작음

---

마무리

CSS 모듈은 React에서 컴포넌트 단위로 스타일을 관리하기 위한 강력한 도구입니다. 클래스 이름 충돌 문제를 해결하고, 깔끔하고 유지보수 가능한 스타일링을 제공합니다. 위의 예제를 활용하여 여러분의 프로젝트에서 CSS 모듈을 도입해 보세요. 필요한 경우 classnames 라이브러리와 함께 사용하면 더욱 유연하게 스타일링을 적용할 수 있습니다.

궁금한 점이나 추가로 알고 싶은 내용이 있다면 댓글로 남겨주세요! 😊