Next.js에서 './globals.css' 모듈을 찾을 수 없는 에러(ts 2882) 해결 방법
Problem
Next.js 프로젝트를 VS Code에서 작업하다 보면 갑자기 import './globals.css'와 같은 CSS 임포트 구문에 빨간 줄이 그어지며 에러가 발생하는 경우가 있습니다. 에러 메시지는 Cannot find module or type declarations for side-effect import of './globals.css' ts(2882)로 나타납니다. 코드를 수정하거나 의존성을 업데이트하지 않았는데도 기존 프로젝트나 심지어 npx create-next-app으로 갓 생성한 새 프로젝트에서도 이 문제가 발생하여 개발자를 당황하게 만듭니다.
Background
기본적으로 TypeScript는 .ts, .tsx, .js, .jsx 파일만을 모듈로 인식하고 처리할 수 있습니다. .css, .svg, .png와 같은 정적 에셋이나 스타일 파일은 TypeScript 컴파일러가 기본적으로 이해하지 못하기 때문에 별도의 타입 선언(Type Declaration)이 없으면 모듈을 찾을 수 없다는 에러를 발생시킵니다.
또한, 이 문제는 VS Code 에디터가 자체적으로 내장하고 있는 전역 TypeScript 버전과 프로젝트의 node_modules에 설치된 로컬 TypeScript 버전이 일치하지 않을 때 종종 발생합니다. Next.js는 내부적으로 CSS 임포트를 처리할 수 있도록 설정되어 있지만, 에디터의 언어 서버가 이를 올바르게 인식하지 못해 발생하는 일종의 에디터 환경 문제입니다.
Solution
이 문제를 해결하는 방법은 크게 두 가지가 있습니다. 에디터 설정을 맞추는 방법과 TypeScript에게 직접 CSS 모듈을 알려주는 방법입니다.
방법 1: VS Code의 TypeScript 버전을 Workspace 버전으로 변경 (권장)
가장 간단하고 근본적인 해결책은 VS Code가 프로젝트에 설치된 TypeScript를 사용하도록 설정하는 것입니다. 이 방법은 추가 코드를 작성할 필요가 없다는 장점이 있습니다.
- VS Code에서 임의의
.tsx또는.ts파일을 엽니다. Ctrl + Shift + P(Mac의 경우Cmd + Shift + P)를 눌러 커맨드 팔레트를 엽니다.TypeScript: Select TypeScript version을 검색하여 선택합니다.- **Use Workspace Version (작업 영역 버전 사용)**을 선택합니다.
이 설정을 마치면 VS Code가 node_modules 내의 TypeScript 라이브러리를 참조하게 되어 에러가 즉시 사라집니다.
방법 2: 전역 타입 선언 파일(d.ts) 추가
만약 첫 번째 방법으로 해결되지 않거나 특정 에디터 설정에 의존하고 싶지 않다면, TypeScript에게 CSS 파일이 유효한 모듈임을 직접 선언해 줄 수 있습니다. 이 방법은 에디터에 종속되지 않고 프로젝트 레벨에서 명시적으로 타입 에러를 방지한다는 장점이 있습니다.
프로젝트 루트 디렉토리에 global.d.ts 또는 css.d.ts 파일을 생성하고 아래 코드를 추가합니다.
// global.d.ts
// 모든 .css 확장자를 가진 파일의 임포트를 모듈로 인식하도록 선언합니다.
declare module "*.css";
이 코드는 TypeScript 컴파일러에게 .css로 끝나는 모든 임포트가 유효한 모듈임을 알려주어 ts(2882) 에러를 우회할 수 있게 해줍니다.
Deep Dive
팀 프로젝트를 진행할 때는 모든 팀원이 동일한 에디터 환경을 갖추는 것이 중요합니다. ‘방법 1’의 설정을 매번 수동으로 하는 대신, 프로젝트 루트에 .vscode/settings.json 파일을 만들고 "typescript.tsdk": "node_modules/typescript/lib" 설정을 추가하면 프로젝트를 여는 모든 팀원의 VS Code가 자동으로 Workspace 버전의 TypeScript를 사용하도록 유도할 수 있습니다.
또한, declare module "*.css"와 같은 앰비언트 모듈 선언(Ambient Module Declaration)은 CSS뿐만 아니라 이미지나 폰트 같은 다른 정적 에셋을 TypeScript 환경에서 다룰 때도 동일하게 적용되는 강력한 패턴입니다. 웹팩(Webpack)이나 터보팩(Turbopack) 같은 번들러가 실제 파일을 처리하더라도, TypeScript 컴파일러를 통과하기 위해서는 이러한 타입 선언이 필수적입니다.
Conclusion
ts(2882) 에러는 실제 코드의 버그라기보다는 VS Code의 TypeScript 언어 서버와 프로젝트 환경 간의 설정 불일치로 인해 발생하는 흔한 문제입니다. 에디터의 TypeScript 버전을 Workspace 버전으로 맞추는 것만으로도 대부분 해결되며, 필요에 따라 전역 .d.ts 파일에 모듈 선언을 추가하여 타입스크립트 컴파일러의 이해도를 높일 수 있습니다. 개인 작업이라면 에디터 설정 변경을, 팀 단위의 확실한 에러 방지가 필요하다면 타입 선언 파일 추가를 추천합니다.