Declaration File

declare 선택은 노출 위치로 결정한다

.d.ts는 실행 코드를 만드는 파일이 아니라, 이미 존재하는 값과 모듈의 타입 계약을 적는 파일입니다. 먼저 값이 어디에 노출되는지 정하면 선언 형태도 거의 정해집니다.

런타임 실제 값은 JS, 브라우저, 패키지가 제공한다.

노출 위치 전역인지, 모듈 import 대상인지 먼저 본다.

목표 타입 검사만 돕고 번들 결과는 바꾸지 않는다.

상황	선언 형태	선택 기준	점검 질문
전역 값 브라우저나 레거시 스크립트가 이미 만든 값	`declare const`, `function`, `class`	import 없이 바로 접근하는 이름이면 전역 선언으로 둔다.	이 선언이 없어도 런타임 값은 실제로 존재하는가?
전역 객체 묶음 한 이름 아래 여러 API가 모인 라이브러리	`declare namespace`	`jQuery.ajax`처럼 객체 내부 멤버를 타입으로 묶는다.	최상위 이름 하나가 API의 진입점 역할을 하는가?
패키지 import 모듈 이름으로 가져오는 JS 패키지	`declare module`	`import ... from "pkg"`가 타입을 알도록 export 모양을 적는다.	호출자는 문자열 모듈 이름으로 이 대상을 가져오는가?
에셋 import 이미지, 스타일, 원시 텍스트 같은 비 TS 파일	`declare module "*.png"`	확장자 패턴을 문자열, URL, 컴포넌트 타입 중 하나로 정한다.	빌드 도구가 실제 변환하고 타입만 비어 있는 상태인가?

전역 계약 예시

declare const MY_GLOBAL_CONFIG: Config;

declare namespace LegacyChart {
  function render(target: string): void;
}

모듈 계약 예시

declare module "my-custom-module" {
  export function init(options: Options): void;
}

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

주의

최상위 export가 있으면 파일은 모듈이 된다

전역 보강이 목적이면 declare global을 쓰거나, 파일의 모듈화 여부를 의도적으로 관리해야 합니다.

기준

타입 선언은 구현을 대신하지 않는다

선언이 통과해도 실제 JS 값이 없으면 런타임 오류가 납니다. .d.ts는 존재하는 API의 모양을 설명하는 계약서입니다.