TypeScript 빌드 에러: Cannot find type definition file for 'minimatch'

프로젝트를 진행하다가 빌드 중 아래와 같은 에러를 만났습니다.

Failed to compile

Cannot find type definition file for 'minimatch'.
The file is in the program because:
Entry point for implicit type library 'minimatch' TS2688

같은 프로젝트를 쓰는 다른 개발자에게서는 문제가 없었기 때문에, 제 로컬 환경이나 IDE 설정 문제라는 생각이 들었습니다.

---

원인 분석

이 에러는 TypeScript가 minimatch의 타입 정의(.d.ts)를 찾지 못할 때 발생합니다.
대표적인 원인은 다음과 같습니다:

1. 로컬/글로벌 TypeScript 버전 불일치
   IDE가 node_modules/typescript 대신 전역 설치된 TS를 참조하면서 발생.
2. 타입 정의 누락
   minimatch는 자체적으로 타입을 제공하지 않고, @types/minimatch 패키지가 필요합니다.
3. tsconfig.json 설정 문제
   "types" 옵션에 불필요하게 minimatch가 들어가 있거나, typeRoots 설정이 꼬여서 발생할 수 있습니다.

 

해결 방법

VS Code(Cursor)에서 로컬 TypeScript 버전 사용하기Cursor(VS Code)에서는 기본적으로 전역 TS를 참조하는데, 이걸 프로젝트 안에 있는 **로컬 TypeScript(node_modules/typescript)**를 쓰도록 바꿔주면 해결됩니다.

1. Ctrl+Shift+P (맥은 Cmd+Shift+P) → 명령 팔레트 열기
2. TypeScript: Select TypeScript Version 입력 후 실행
3. Use Workspace Version 선택

이렇게 설정을 바꾸고 나니, 빌드 에러가 바로 사라졌습니다.

---

정리

• 같은 프로젝트인데 나만 에러가 난다면, IDE가 전역 TS를 참조 중일 가능성이 크다.
• Cursor에서 Use Workspace Version을 선택하면 로컬 TS 버전을 사용하게 되어 문제 해결.

• 설정 방법
• 에러의 원인은 IDE가 전역(global)에 설치된 TypeScript를 사용하면서 발생한 것이었습니다.