CSS Modules

Docs

• Next.js - CSS

Next.js가 Global CSS를 제한하는 이유

CSS는 기본적으로 전역 스코프를 가진다. 이로 인해 여러 컴포넌트에서 동일한 클래스 이름을 사용할 경우, 의도하지 않은 스타일 충돌이 발생할 수 있다.

이러한 문제를 방지하기 위해 Next.js는 Global CSS를 import할 수 있는 위치를 의도적으로 제한한다.

• Page Router: pages/_app.tsx
• App Router: app/layout.tsx

즉, 애플리케이션의 엔트리 지점에서만 전역 스타일을 선언할 수 있으며,
개별 컴포넌트나 일반적인 React 컴포넌트 파일에서는 Global CSS를 import하는 것이 허용되지 않는다.

이는 전역 스타일의 영향 범위를 명확히 하고, 컴포넌트 단위 스타일링을 유도하기 위한 설계다.

CSS Modules

CSS Modules는 파일 단위로 스타일의 스코프를 분리해, 각 컴포넌트가 자신의 스타일만 갖도록 만드는 방식이다.
.module.css 확장자를 사용하는 경우, 해당 스타일은 자동으로 로컬 스코프로 처리된다.

예시 index.module.css

.h1 {
  color: red;
}

.h2 {
  color: brown;
}

import style from './index.module.css';

export default function Home() {
  return (
    <>
      <h1 className={style.h1}>Index</h1>
      <h2 className={style.h2}>H2</h2>
    </>
  );
}

이때 실제 브라우저에 적용되는 클래스 이름은 고유하게 생성된다.
(ex. index_h1__JHo3j, index_h2__Txrlj )

이 방식 덕분에 서로 다른 컴포넌트에서 동일한 클래스 이름을 사용하더라도 스타일 충돌이 발생하지 않는다.

전역으로 적용되어야 하는 reset, typography, theme 변수 등은 Global CSS로 관리하는 것이 적절하다.