minstudio

선언 병합과 글로벌 모듈 확장

타입스크립트의 interface는 동일한 이름으로 여러 번 선언하면, 덮어쓰는 것이 아니라 모두 하나로 합쳐지는 특성(Declaration Merging)을 가집니다.

이 특성을 활용하면 우리가 직접 작성하지 않은 브라우저의 Window 객체나 외부 라이브러리의 타입에, 내가 만든 커스텀 속성을 안전하게 끼워 넣을 수 있습니다.

🧩 인터페이스 선언 병합 (Declaration Merging) TypeScript 내장 타입 interface Window { location: Location; } 내가 작성한 추가 선언 interface Window { myAppEnv: string; } + ✅ 자동 병합된 최종 타입 interface Window { location: Location; myAppEnv: string; } 
<!-- ==========================================
// 📂 ts-advanced/declaration-merging.ts
// ========================================== -->
<script>
// 1. 기초 선언 병합
// 같은 이름의 인터페이스를 두 번 작성하면 에러가 나지 않고 합쳐집니다.
interface Box {
  height: number;
  width: number;
}

interface Box {
  scale: number; // 기존 Box에 scale 속성이 추가됨!
}

const myBox: Box = { height: 5, width: 6, scale: 10 };

// 2. 실무 예제: Window 전역 객체 확장하기
// 바닐라 자바스크립트에서는 window.MyAPI = {...} 로 자유롭게 값을 넣을 수 있지만,
// TS에서는 "Window 타입에 MyAPI가 없다"며 에러를 냅니다.
// 이때 선언 병합을 이용해 전역 타입을 확장해 줍니다.

declare global {
  // Window 인터페이스를 확장합니다 (덮어쓰기가 아님!)
  interface Window {
    MyAPI: {
      loadConfig: () => void;
      apiKey: string;
    }
  }
}

// 이제 TS 에러 없이 브라우저 window 객체에 안전하게 접근/할당할 수 있습니다!
window.MyAPI = {
  loadConfig: () => console.log("Config loaded!"),
  apiKey: "1234-abcd"
};

window.MyAPI.loadConfig(); // OK, 자동완성 지원
</script>
선언 병합과 글로벌 모듈 확장 | Minstudio