CSS 모듈 사용하기
웹 애플리케이션의 시각적인 매력과 사용자 경험은 스타일링(Styling) 에 크게 좌우됩니다. React 기반의 Next.js 애플리케이션에서 스타일을 적용하는 방법은 다양하지만, 그중에서도 CSS 모듈(CSS Modules) 은 컴포넌트 기반의 개발 철학과 잘 맞아 떨어지며, 스타일 충돌을 방지하고 관리 효율성을 높이는 강력한 기능을 제공합니다.
이 절에서는 CSS 모듈이 무엇인지, 왜 필요한지, 그리고 Next.js 프로젝트에서 어떻게 활용하는지에 대해 자세히 알아보겠습니다.
CSS 모듈이란 무엇인가요?
CSS 모듈은 CSS 파일을 불러올 때, 모든 클래스 이름과 애니메이션 이름을 자동으로 고유하게 만들어 컴포넌트 범위로 스타일을 한정하는 방식입니다. 이는 전역적인 스타일 충돌 문제를 해결하고, CSS의 스코프를 명확히 하여 유지보수성을 높이는 데 기여합니다.
핵심 특징
- 로컬 스코프(Local Scope) 스타일: CSS 모듈로 작성된 클래스 이름은 해당 모듈(파일) 내에서만 유효합니다. 다른 컴포넌트의 동일한 클래스 이름과 충돌하지 않습니다.
- 고유한 클래스 이름 생성: 빌드 시
[filename]\_[classname]\_\_[hash]와 같은 형태로 고유한 클래스 이름이 자동으로 생성됩니다. (예:button\_module\_\_btn\_\_abc123) - 파일 기반 모듈화: 각 CSS 파일이 독립적인 모듈처럼 작동하여, 특정 컴포넌트의 스타일은 해당 컴포넌트의 CSS 파일에만 존재합니다.
- JavaScript를 통한 스타일 임포트: CSS 파일을 JavaScript/TypeScript 코드에서 직접
import하여 사용합니다.
왜 CSS 모듈을 사용해야 할까요?
전통적인 CSS 작성 방식이나 다른 스타일링 방법에는 다음과 같은 문제점들이 있었습니다.
전역 스코프 문제 (Global Scope Pollution)
- 모든 CSS 클래스 이름은 기본적으로 전역 스코프를 가집니다.
- 다른 컴포넌트나 페이지에서 의도치 않게 동일한 클래스 이름을 사용하면 스타일이 덮어씌워지는 충돌(Collision) 이 발생합니다.
- 이는 특히 규모가 큰 프로젝트나 여러 개발자가 협업하는 환경에서 디버깅을 어렵게 하고 유지보수를 복잡하게 만듭니다.
스타일 간의 의존성 및 관리의 어려움
- 어떤 스타일이 어떤 HTML 요소에 적용될지 파악하기 어렵습니다.
- 컴포넌트 삭제 시 해당 스타일을 안전하게 삭제할 수 있는지 확신하기 어렵습니다. (데드 코드)
CSS 모듈은 이러한 문제들을 다음과 같이 해결합니다
- 스타일 고립: 각 컴포넌트의 스타일이 해당 컴포넌트에만 영향을 미치도록 합니다. 클래스 이름 충돌 걱정 없이 자유롭게 클래스 이름을 지을 수 있습니다.
- 모듈화된 CSS: CSS 파일 자체가 컴포넌트에 종속적인 모듈이 되어, 컴포넌트와 스타일 간의 강한 연관성을 확보합니다. 컴포넌트 삭제 시 관련 CSS 파일을 함께 삭제해도 다른 곳에 영향을 미 주지 않습니다.
- 명확한 의존성: 컴포넌트 파일에서 CSS 파일을 직접 임포트하므로, 어떤 컴포넌트가 어떤 스타일을 사용하는지 명확하게 알 수 있습니다.
Next.js에서 CSS 모듈 사용하기
Next.js는 CSS 모듈을 기본적으로 지원하며, 추가 설정 없이 바로 사용할 수 있습니다. 파일 이름을 [name].module.css 또는 [name].module.scss, [name].module.sass와 같이 .module. 확장자를 사용하여 작성하면 됩니다.
실습: 버튼 컴포넌트에 CSS 모듈 적용하기
간단한 버튼 컴포넌트를 만들고 CSS 모듈을 사용하여 스타일을 적용해 봅시다.
src/app/css-modules/page.tsx 파일 생성 (서버 컴포넌트):
이 페이지는 서버 컴포넌트이며, 우리가 만들 클라이언트 컴포넌트 StyledButton을 임포트하여 사용합니다.
// src/app/css-modules/page.tsx
import StyledButton from './StyledButton'; // 클라이언트 컴포넌트 임포트
import styles from './page.module.css'; // 페이지에 전역적으로 적용될 CSS 모듈 임포트 (예시)
export default function CssModulesPage() {
return (
<div className={styles.container}>
<h1 className={styles.title}>CSS 모듈 사용 예제</h1>
<p className={styles.description}>
아래 버튼은 CSS 모듈을 사용하여 고유한 스타일을 가집니다.
</p>
<div style={{ display: 'flex', gap: '20px', marginTop: '30px' }}>
<StyledButton label="클릭하세요" />
<StyledButton label="다른 버튼" primary={true} />
</div>
</div>
);
}src/app/css-modules/page.module.css 파일 생성:
page.tsx에 적용될 기본적인 레이아웃 스타일을 정의합니다.
/* src/app/css-modules/page.module.css */
.container {
padding: 40px;
max-width: 800px;
margin: 20px auto;
background-color: #f8f8f8;
border-radius: 10px;
box-shadow: 0 4px 15px rgba(0, 0, 0, 0.1);
text-align: center;
}
.title {
color: #333;
margin-bottom: 15px;
font-size: 2.5em;
}
.description {
color: #666;
font-size: 1.1em;
line-height: 1.6;
}src/app/css-modules/StyledButton.tsx 파일 생성 (클라이언트 컴포넌트):
버튼 컴포넌트와 해당 스타일을 정의합니다.
"use client"; // 클라이언트 컴포넌트임을 명시
import React from 'react';
import buttonStyles from './StyledButton.module.css'; // 🚨 CSS 모듈 임포트
interface StyledButtonProps {
label: string;
primary?: boolean;
onClick?: () => void;
}
export default function StyledButton({ label, primary = false, onClick }: StyledButtonProps) {
return (
<button
// CSS 모듈에서 클래스 이름에 접근: buttonStyles.btn, buttonStyles.primary
className={`${buttonStyles.btn} ${primary ? buttonStyles.primary : ''}`}
onClick={onClick}
>
{label}
</button>
);
}src/app/css-modules/StyledButton.module.css 파일 생성:
StyledButton 컴포넌트에 적용될 스타일을 정의합니다.
.btn {
padding: 12px 25px;
font-size: 1.1em;
border: none;
border-radius: 8px;
cursor: pointer;
transition: background-color 0.3s ease, transform 0.1s ease;
font-weight: bold;
box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
}
.btn:hover {
transform: translateY(-2px);
}
.btn:active {
transform: translateY(0);
box-shadow: none;
}
/* 기본 버튼 스타일 */
.btn {
background-color: #007bff;
color: white;
}
/* primary prop이 true일 때 적용될 스타일 */
.primary {
background-color: #28a745;
color: white;
}
.primary:hover {
background-color: #218838;
}실습 확인:
개발 서버(npm run dev)를 실행한 후, http://localhost:3000/css-modules로 접속합니다.
- 두 개의 버튼이 서로 다른 배경색을 가지고 있는 것을 확인할 수 있습니다.
- 브라우저 개발자 도구(Elements 탭)를 열어 버튼의 클래스 이름을 확인해 보세요.
StyledButton_module__btn__...와 같이 고유한 해시값이 붙어 있는 것을 볼 수 있습니다. 이는 스타일 충돌을 방지하기 위해 CSS 모듈이 자동으로 생성한 고유한 클래스 이름입니다. page.module.css의 클래스 이름도 유사하게 고유한 이름으로 변환됩니다.
CSS 모듈과 일반 CSS의 차이점
| 특징 | 일반 CSS (.css) | CSS 모듈 (.module.css) |
|---|---|---|
| 스코프 | 전역 (Global Scope) | 로컬 (Local Scope) |
| 클래스 이름 | 작성된 이름 그대로 사용 | 자동으로 고유한 이름으로 변환 |
| 충돌 방지 | 수동으로 관리 (BEM, 네이밍 컨벤션 등) | 자동 처리 |
| 임포트 방식 | <link> 태그 또는 @import (전역) | JavaScript/TypeScript 파일에서 import styles from './styles.module.css' |
| 재사용성 | 전역적 재사용 | 컴포넌트 기반 재사용 (모듈별) |
| 유지보수성 | 규모가 커질수록 어려움 | 명확한 의존성, 쉬운 삭제 |
SCSS/SASS와 CSS 모듈 함께 사용하기
Next.js는 CSS 모듈과 함께 SCSS/SASS도 기본적으로 지원합니다. node-sass 또는 sass 패키지를 설치한 후, 파일 확장자를 .module.scss 또는 .module.sass로 변경하여 사용하면 됩니다.
SCSS/SASS 설치
npm install sass
# 또는
yarn add sass파일 이름 변경:
StyledButton.module.css를 StyledButton.module.scss로 변경하고, SCSS 문법(중첩, 변수 등)을 사용할 수 있습니다.
$primary-color: #28a745;
$default-color: #007bff;
.btn {
padding: 12px 25px;
font-size: 1.1em;
border: none;
border-radius: 8px;
cursor: pointer;
transition: background-color 0.3s ease, transform 0.1s ease;
font-weight: bold;
box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
&:hover { // SCSS 중첩 문법
transform: translateY(-2px);
}
&:active {
transform: translateY(0);
box-shadow: none;
}
/* 기본 버튼 스타일 */
background-color: $default-color; // SCSS 변수 사용
color: white;
}
/* primary prop이 true일 때 적용될 스타일 */
.primary {
background-color: $primary-color;
color: white;
&:hover {
background-color: darken($primary-color, 10%); // SCSS 함수 사용
}
}컴포넌트에서 임포트 경로 변경
import buttonStyles from './StyledButton.module.scss'; // 🚨 확장자를 .scss로 변경
// ...이제 SCSS의 강력한 기능을 CSS 모듈의 안전한 스코프 안에서 활용할 수 있습니다.
CSS 모듈은 컴포넌트 기반 개발에서 스타일 관리의 복잡성을 크게 줄여주는 효과적인 방법입니다. Next.js에서 기본적으로 지원하므로, 새로운 프로젝트를 시작할 때 스타일링 방식으로 고려하는 것이 좋습니다.