Typescript Error(TS 2882) : 🤯 "globals.css 모듈을 찾을 수 없습니다" TypeScript 오류, 4단계 해결 여정

 

Next.js와 TypeScript로 프로젝트를 진행하다 보면, 분명히 파일 경로도 맞고 설정도 올바른데 import './globals.css' 같은 구문에서 "ts(2882): 부수 효과 가져오기에 대한 모듈 또는 형식 선언을 찾을 수 없습니다." 라는 오류가 발생하며 발목을 잡힐 때가 있습니다.

 

저 또한 이 문제로 오랜 시간을 소모했고, 저처럼 고민하고 있을 분들에게 도움이 되고자 제가 겪었던 해결 과정을 공유합니다.

 

---

✅ 방법 1: TypeScript에게 CSS 파일 알려주기 (global.d.ts)

가장 먼저 시도할 기본적인 방법입니다. TypeScript는 .ts나 .js 파일이 아니면 그 타입을 알지 못하기 때문에, .css 파일을 모듈로 인식할 수 있다는 것을 알려줘야 합니다.

 

프로젝트 최상위 폴더(root)에 global.d.ts 파일을 생성하고 아래 내용을 추가합니다.

/* global.d.ts */

declare module '*.css';

이 한 줄의 코드는 프로젝트 내의 모든 .css 파일을 유효한 모듈로 선언하는 역할을 합니다.

---

✅ 방법 2: TypeScript 설정 점검하기 (tsconfig.json)

global.d.ts 파일을 만들었음에도 TypeScript가 이를 읽지 못하면 아무 소용이 없습니다. tsconfig.json 파일이 이 타입 선언 파일을 제대로 포함하고 있는지, 그리고 경로 설정이 올바른지 확인해야 합니다.

세 가지를 꼭 확인해 보세요:

1. include 배열: global.d.ts 파일이 include 배열에 포함되어 있는지 확인합니다.
2. baseUrl 설정: 경로 별칭(@/components/*)을 사용한다면, 그 기준이 되는 "baseUrl": "." 설정이 compilerOptions에 있는지 확인합니다.
3. 상대 경로 사용: 전역 CSS 파일은 복잡한 별칭보다 간단한 상대 경로(import './globals.css')로 불러오는 것이 가장 안전하고 명확합니다.

/* tsconfig.json */
{
  "compilerOptions": {
    // ... 다른 설정들
    "baseUrl": ".", // 👈 경로 별칭의 기준점
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    "global.d.ts" // 👈 타입 선언 파일 포함
  ],
  "exclude": ["node_modules"]
}

 

---

✅ 방법 3: 개발 환경 의심하기

위의 코드 레벨 설정이 모두 완벽하다면, 이제는 코드 밖의 환경을 의심해 볼 차례입니다.

• Next.js 플러그인 비활성화: 드물지만, 특정 Next.js 버전과 tsconfig.json의 plugins 설정이 충돌할 수 있습니다. 잠시 주석 처리하고 VS Code를 재시작해서 확인해 보세요.
• VS Code 확장 프로그램 비활성화: 다른 확장 프로그램(Linter, Formatter 등)이 TypeScript의 타입 검사를 방해할 수 있습니다. 모든 명령 표시 창에서 Developer: Reload Window with Extensions Disabled를 실행해 확장 프로그램 없이 문제가 해결되는지 확인해 보세요.
• 프로젝트 재설치: .next, node_modules 폴더에 꼬여버린 캐시가 문제일 수 있습니다. 해당 폴더들을 삭제하고 pnpm install (혹은 npm install)로 의존성을 다시 설치해 보세요.

---

💡 방법 4: VS Code의 TypeScript 버전 변경하기 (저의 최종 해결책!)

만약 위의 3가지 방법을 모두 시도했는데도 문제가 해결되지 않았다면, 이 방법을 시도해 보세요. 저를 괴롭혔던 문제의 최종 원인은 바로 여기에 있었습니다.

VS Code는 자체적으로 내장된 TypeScript 버전을 사용하기도 하고, 현재 프로젝트의 node_modules에 설치된 버전을 사용하기도 합니다. 이 둘의 버전이 맞지 않으면 설정 파일을 올바르게 해석하지 못하는 문제가 발생할 수 있습니다.

해결 방법은 VS Code가 프로젝트의 TypeScript 버전을 사용하도록 명시해 주는 것입니다.

1. 모든 명령 표시창 열기
   • Mac: Cmd + Shift + P
   • Windows: Ctrl + Shift + P
2. TypeScript 버전 선택
   • 명령창에 TypeScript: Select TypeScript Version... 또는 TypeScript: TypeScript 버전 선택... 을 입력합니다.
   • 나타나는 선택지에서 "작업 영역 버전 사용(Use Workspace Version)"을 클릭합니다.
   • 작업 영역 버전은 현재 프로젝트의 package.json에 명시된 버전을 의미합니다.

 

저는 이 4번째 방법을 통해 드디어 지긋지긋한 타입 오류에서 벗어날 수 있었습니다. 이 글이 저와 같은 문제로 어려움을 겪는 분들께 조금이나마 도움이 되기를 바랍니다. 🙏