[트러블슈팅] TypeScript에서 CSS / 이미지 import 시 오류 발생

목차 (OPEN)

• 🧩 문제 상황
• 🛠 해결 방법
• 💡 교훈
• 🔎 전체 코드

 

 

 

🧩 문제 상황

Vite + React + TypeScript 환경에서

.css나 .png 파일을 import 하니까

아래와 같은 에러가 발생했다.

 

Cannot find module './style.css' or its corresponding type declarations.

Cannot find module './logo.png' or its corresponding type declarations.

 

처음에는 그냥 경로 문제인 줄 알았는데,

실제 원인은 TypeScript가 해당 파일 형식을

이해하지 못해서 생긴 타입 오류임을 알게 되었다.

 

---

🛠 해결 방법

직접 타입 선언 파일을 만들어서

TypeScript에게 이런 파일도 import 가능하다고 알려줘야 했다.

 

// 📄 declarations.d.ts

// CSS 모듈 선언
declare module '*.css' {
  const content: { [className: string]: string };
  export default content;
}

// 이미지 파일 선언
declare module '*.png' {
  const src: string;
  export default src;
}

 

그리고 tsconfig.json에도 types 경로가 제대로 포함되어 있어야 한다.

보통은 include 항목에 "types" 또는 "types/*.d.ts"를 추가한다고 해서

아래와 같이 해주었다.

 

{
  "include": ["src", "types"]
}

 

---

💡 교훈

TypeScript는 기본적으로 .ts / .tsx 외의 다른 파일 타입은 알 수 없기 때문에

직접 타입 선언을 해줘야만 에러 없이 사용 가능하다는 것을 알게 되었다.

 

.css, .png, .svg 등 정적 자원을 사용하는 프로젝트에서는

초기 세팅 시 declarations.d.ts 파일을 꼭 준비해둬야 겠다.

 

---

🔎 전체 코드

📄 declarations.d.ts 전체 코드

 

📄 tsconfig.json 전체 코드