TypeScript에서 CSS Modules 사용할 때 .d.ts 파일이 필요한 이유
"분명 CSS는 적용됐는데 빨간 줄이 계속 뜬다… 왜 그럴까?"
React 프로젝트를 TypeScript로 개발하다 보면, CSS Modules를 사용할 때 이런 경험을 한 번쯤 하게 된다.
스타일은 잘 적용되는데, VSCode에서는 계속 빨간 밑줄이 생기고 빌드 시 타입 오류가 발생하는 현상이다.
이 글에서는 이 문제의 원인과 해결 방법, 그리고 .d.ts 파일이 필요한 이유를 정리한다.
문제 상황
예를 들어, 다음과 같이 CSS Modules를 사용하는 코드가 있다고 가정한다.
import styles from './MyComponent.module.css'
const MyComponent = () => {
return <div className={styles.container}>Hello</div>
}이 코드는 실제로 스타일이 잘 적용되고 화면에도 정상적으로 나타난다.
하지만 TypeScript는 아래와 같은 오류를 발생시킨다.
Cannot find module './MyComponent.module.css' or its corresponding type declarations.CSS 파일을 import했지만, TypeScript는 이 파일의 타입이 어떤 것인지 알 수 없기 때문에 오류가 발생하는 것이다.
TypeScript는 CSS 타입을 알지 못한다
TypeScript는 기본적으로 .css 파일의 구조를 이해하지 못한다.
자바스크립트에서는 넘어가는 부분이지만, TypeScript는 **"이 파일이 어떤 값을 export하는지"**를 명확하게 알아야 한다.
해결 방법: .d.ts 타입 선언 추가
해결 방법은 간단하다. 프로젝트에 아래와 같은 타입 선언 파일을 하나 추가하면 된다.
src/
└── types/
└── index.d.ts// src/types/index.d.ts
declare module '*.module.css' {
const classes: { [key: string]: string }
export default classes
}이렇게 선언해주면 TypeScript는 .module.css 파일을 import할 때
styles.someClass 형태로 사용할 수 있다는 것을 알게 된다.
꼭 필요한가?
| 항목 | 설명 |
|---|---|
| 실행에는 영향 없음 | CSS는 그대로 잘 적용된다. |
| 타입 검사에는 영향 있음 | TypeScript와 VSCode에서 오류 없이 개발하려면 필요하다. |
| 자동완성 및 정적 분석 | CSS 클래스 이름도 자동완성으로 확인할 수 있다. |
정리
- CSS Modules를 TypeScript와 함께 사용할 때는
.d.ts타입 선언이 필요하다. - 실행에는 영향이 없지만, 타입 오류를 방지하고 개발 효율을 높이기 위해 반드시 추가하는 것이 좋다.
- 선언 파일의 위치는
src/global.d.ts,src/types/index.d.ts등으로 자유롭게 구성할 수 있다.
마무리
TypeScript는 엄격한 타입 시스템을 통해 안정적인 개발을 지원하지만, 이렇게 명시적인 설정이 필요한 경우도 존재한다.
한 줄의 타입 선언으로 코드 품질을 높일 수 있다면, 굳이 마다할 이유는 없다.
팀 프로젝트라면, 이 설정이 누락된 상태에서 전 팀원이 모두 동일한 타입 오류를 마주할 수도 있다.
