TypeScript로 전환 후 Vite + React에서 발생한 모듈 경로 오류, 해결책은 단순히 VSCode 재시작?

Vite + React 환경에서 .jsx 파일을 .tsx로 변경한 후, 모듈에 대한 선언 파일을 찾을 수 없습니다라는 TypeScript 오류를 마주한 적이 있는가? 나도 동일한 문제를 겪었다. tsconfig.json을 열심히 뒤져보고, Vite 설정까지 점검했지만, 해결책은 의외로 간단했다.

✅ 문제 상황

Vite 프로젝트에서 .tsx 파일을 import할 때, 아래와 같은 에러가 발생했다:

모듈 './Login'에 대한 선언 파일을 찾을 수 없습니다. 'c:/Users/프로젝트경로/src/Login.tsx'에는 암시적으로 'any' 형식이 포함됩니다.ts(7016)

이 오류는 TypeScript가 .tsx 파일을 인식하지 못하거나 경로를 제대로 읽지 못할 때 발생한다. tsconfig.json의 경로 설정이 잘못되었거나, VSCode가 변경 사항을 인식하지 못한 경우다.

✅ 문제 원인 분석

이 오류의 원인은 다름 아닌 VSCode의 캐시 문제였다.

VSCode는 프로젝트를 열 때 tsconfig.json의 설정을 메모리에 캐싱해둔다. 그런데 .jsx에서 .tsx로 확장자를 변경하거나 파일 경로를 수정하면, TypeScript 서버가 이를 즉시 반영하지 못할 수 있다.

이 경우, TypeScript 서버는 기존 캐시를 사용해 여전히 .tsx 파일을 찾지 못한다고 인식하게 된다.

✅ 해결 방법

해결 방법은 아주 간단하다. 아래 두 가지 방법 중 하나만 수행하면 된다:

VSCode 재시작:

파일 경로나 설정이 변경되었을 때, VSCode가 이를 즉시 반영하지 못하는 경우가 있다.

따라서 VSCode를 완전히 종료하고 다시 실행하면 설정이 새로 반영된다.

TypeScript 서버 재시작:

Ctrl + Shift + P 또는 Cmd + Shift + P를 눌러 명령어 팔레트를 열고 TypeScript: Restart TS Server를 입력하고 실행한다.

이 과정에서 TypeScript 서버의 캐시가 초기화되고, 새로운 경로 설정이 반영된다.

✅ 왜 VSCode 재시작이 효과적일까?

VSCode는 프로젝트를 열 때 tsconfig.json과 vite.config.ts의 설정을 메모리에 저장한다.

.jsx에서 .tsx로 파일 확장자를 변경하거나, tsconfig.json의 include 경로를 수정해도, TypeScript 서버가 이를 즉시 반영하지 못할 때가 있다.

이럴 경우, VSCode를 재시작하거나 TypeScript 서버를 재시작하면, 캐시가 초기화되면서 새로운 설정이 반영된다.

✅ 결론

TypeScript 설정 파일을 아무리 수정해도 에러가 해결되지 않는다면, 가장 먼저 시도해볼 해결책은 VSCode 재시작이다.

TypeScript 서버가 새로운 설정을 인식하지 못할 때, 가장 빠른 해결책은 재시작이다.

작은 오류도 해결 과정에서 큰 배움이 될 수 있다. 이번 경험을 통해 VSCode의 캐시 시스템이 어떻게 동작하는지, 그리고 재시작이 왜 강력한 해결책인지 확실히 알게 되었다.