Declaration Resolution

@types와 선언 파일 해석 순서

타입 선언 충돌은 패키지 자체 타입, DefinitelyTyped, typeRoots, module augmentation이 어떤 순서로 적용되는지 보면 풀립니다.

01

패키지 타입 확인

package.json의 types 또는 exports 타입 조건이 먼저 후보가 됩니다.

Bundled
02

@types 탐색

패키지에 선언이 없으면 node_modules/@types에서 이름이 맞는 선언을 찾습니다.

DefinitelyTyped
03

설정 제한

types가 지정되면 포함할 전역 타입 패키지가 명시 목록으로 줄어듭니다.

types
04

루트 변경

typeRoots는 탐색 위치 자체를 바꾸므로 기본 @types 탐색을 의도치 않게 끊을 수 있습니다.

typeRoots
05

선언 병합

module augmentation과 global 선언이 기존 타입에 합쳐지는 위치를 확인합니다.

Merge
Cannot find type
선언 탐색 실패 패키지 자체 타입, @types 설치, tsconfig types/typeRoots 제한을 차례로 확인합니다.
traceResolution 도움
Duplicate identifier
전역 선언 충돌 서로 다른 버전의 @types나 lib 설정이 같은 전역 이름을 선언할 수 있습니다.
버전 정렬
Augmentation 실패
모듈 이름 불일치 declare module의 문자열이 실제 import specifier와 정확히 맞는지 봅니다.
paths 영향 확인

@types 해석 순서 점검

전역 최소화 global 선언은 필요한 범위로 줄이고 모듈 선언을 우선합니다.
설정 의도 types와 typeRoots는 문제 해결용 임시 설정으로 남지 않게 이유를 기록합니다.
버전 동기화 라이브러리 버전과 @types 버전이 크게 어긋나면 타입만 맞고 런타임은 깨질 수 있습니다.