CSS Import TypeScript 에러 (ts(2882))

문제

한번씩 꼭 만나는 에러인 것 같다. (참고로 개발 환경은 next.js 프레임워크)

Cannot find module or type declarations for side-effect import of './globals.css'.ts(2882)

맨날 이 에러가 뜨면 claude code나 gemini cli에게 해결해달라하고 엔터를 딸깍으로 고치는데 그냥 내가 한번 고쳐보고 싶었다.

일단 이 문제를 자세히 들여다보자 (파파고형님이 먼저 번역을 해줄 것 이다)

'.\globals.css.ts(2882)'의 부작용 가져오기에 대한 모듈 또는 형식 선언을 찾을 수 없습니다

즉, typeScript가 .css파일을 import할 때 해당 모듈의 타입 선언을 찾지 못해서 발생하는 에러이다.

그럼 왜 발생할까?

1. typeScript는 기본적으로 .css 파일이 뭔지 모른다.
2. Next.js의 next-env.d.ts가 CSS 타입을 자동으로 제공해야 하지만, 일부 환경에서 누락되는 경우가 있다.

---

어떻게 해결하는디?

1. /src/types 경로에 global.d.ts 파일을 생성한다.

2. 아래 코드를 해당 파일에 작성한다.

declare module "*.css" {
const content: { [className: string]: string };
export default content;
}

-> 그럼 해결됨!

---

왜 해결이 되는지 자세히 살펴보자

먼저 해결 이유를 알아보기 전에 왜 이 에러가 발생했는지 부터 차근차근 알아보자. typeScript는 모든 import를 타입으로 이해해야 컴파일할 수 있다.

import "./globals.css";  // TypeScript: "이게 뭔데?"

정리해서 typeScript는 .ts, .tsx, .js 파일만 기본적으로 이해한다. 즉 .css 파일은 모르는 확장자라서 에러가 발생하는 것이다.

이제 declare module이 하는 일에 대해 살펴보자. 위 코드는 typeScript에게
1. *.css 패턴의 모든 파일을 모듈로 인식해라
2. 이 모듈은 객체를 export한다

라고 타입 정보를 알려주는 것이다.

실제 런타임과의 관계

• 빌드 시: Webpack/Next.js가 실제로 CSS를 처리한다.
• 타입 체크 시: typeScript는 global.d.ts를 보고 "아 CSS 파일이구나" 하고 넘어간다

즉, global.d.ts는 typeScript를 속이는 용도이다. (실제 css 처리는 번들러가 담당한다)

Next.js에서 왜 필요했나?

보통 Next.js는 next-env.d.ts에서 이걸 자동 처리하는데, 프로젝트 설정이나 TypeScript 버전에 따라 누락되는 경우가 있다.

쨌든, 다시 이 오류를 만나면

없애버리겠다.