TypeScript 선언 파일

앰비언트 모듈 선언이 메우는 타입 공백

타입이 없는 외부 모듈이나 asset import는 declare module로 컴파일러에게 모듈의 형태를 알려야 한다.

01

타입 공백 발견

Cannot find module 또는 암시적 any 오류가 외부 모듈 경계에서 발생한다.

missing type
02

선언 범위 선택

패키지 전체, 특정 확장자, 특정 export 형태 중 필요한 만큼만 선언한다.

narrow declare
03

컴파일 포함

tsconfig include/typeRoots가 선언 파일을 읽는지 확인한다.

visible to TS
04

정확도 개선

처음엔 최소 선언으로 막고 실제 사용 API가 늘면 unknown과 구체 타입으로 좁힌다.

evolve
패키지
타입 없는 라이브러리는 실제 export 이름과 함수 시그니처를 선언한다. @types 패키지가 있는지 먼저 확인한다.
prefer official types
Asset
svg, png, css module import는 빌드 도구 규칙과 맞춰 선언한다. ReactComponent export 같은 관례는 프로젝트 설정과 일치해야 한다.
toolchain match
Global
전역 선언은 충돌 위험이 커서 이름과 범위를 좁힌다. declare global은 모듈 파일 안에서 명시적으로 사용한다.
avoid pollution

선언 파일 점검

any 최소화 모든 export를 any로 열어두지 않는다.
include 새 d.ts 파일이 tsconfig에 포함되어 실제로 작동한다.
실제 API 선언이 런타임 모듈의 export 형태와 맞는다.

모듈 선언 예시

declare module "*.svg" {
  const src: string;
  export default src;
}