TypeScript는 import 문자열에서 선언 파일 위치를 추적한다

같은 .d.ts라도 모듈 옆, 전역 선언, 패키지 산출물 중 어디에 있느냐에 따라 해석 경로가 달라진다.

import import { trim } from "./StringUtils"

source src/StringUtils.js

typing src/StringUtils.d.ts

1. 모듈 옆 선언 가져온 파일 옆의 선언 파일이 함수 시그니처를 바로 보완한다.

2. 전역 선언 import 없이 쓰는 이름은 include된 global.d.ts에서 찾는다.

3. 패키지 선언 배포 패키지는 package.json의 types 필드가 진입점이다.

local module

구현 파일과 선언 파일을 나란히 둔다

JS 구현을 유지하면서 타입만 보강할 때 import 경로와 가장 강하게 연결된다.

global scope

브라우저 전역, 레거시 스크립트, Window 확장은 파일 위치보다 tsconfig 포함 여부가 중요하다.

published package

빌드 결과의 선언 파일이 패키지 루트에서 명확히 노출되어야 자동 완성이 살아난다.

점검	확인할 위치	깨졌을 때 증상
모듈 옆 선언	StringUtils.js / StringUtils.d.ts	import는 되지만 함수 인자와 반환 타입이 any로 보인다.
전역 선언	global.d.ts, tsconfig include	브라우저 전역 값이나 Window 확장을 찾지 못한다.
패키지 선언	dist/index.d.ts, package.json types	배포 후 라이브러리 소비자 쪽에서 타입이 사라진다.

핵심: 선언 파일은 “어디에 놓았는가”보다 “TypeScript가 어떤 문자열과 설정을 통해 그 파일까지 도달하는가”로 검증한다.