모듈명 일치
import 문자열과 declare module 이름이 완전히 같아야 합니다.
선언 파일은 실제 import 표면과 맞춰 검증한다
declare module은 런타임을 만들지 않습니다. 모듈 이름, export 형태, 와일드카드 범위가 실제 사용 코드와 맞아야 합니다.
내보내기 형태
default, named, namespace export를 실제 런타임과 맞춥니다.
와일드카드 폭
*.svg처럼 필요한 확장자만 열고 반환 타입을 좁힙니다.
전역 오염
Window 확장과 declare var는 필요한 이름만 최소로 둡니다.
변경 추적
라이브러리 버전이 바뀌면 선언도 함께 갱신합니다.
1
실제 사용 작성
import와 호출 예시를 먼저 둡니다.
2
표면만 선언
사용하지 않는 API까지 넓게 열지 않습니다.
3
컴파일 확인
타입 오류와 자동 완성 결과를 함께 봅니다.
4
런타임 대조
실행 시 없는 export를 타입으로 만들지 않습니다.
verify: import sample -> declare surface -> tsc --noEmit -> 런타임 export 점검
앰비언트 선언은 컴파일러를 안심시키는 약속입니다. 약속이 런타임과 어긋나면 타입 안전성이 아니라 숨은 버그가 됩니다.