ambient global

전역 스크립트 타입은 모듈 선언으로 감싸지 않는다

HTML이 직접 불러온 스크립트의 값은 import 가능한 모듈이 아니라 프로젝트 전역 계약으로 선언해야 타입 검사가 맞습니다.

값 하나

declare var MY_APP처럼 런타임 전역 이름을 그대로 고정합니다.

브라우저 객체 확장

interface Window에 분석 SDK나 외부 도구 속성을 추가합니다.

묶음 API

declare namespace로 여러 함수와 클래스를 한 이름 아래 묶습니다.

선언 대상 판단표

순서 대상 선언 형태 판단 기준
01 전역 설정 객체 declare var MY_APP 외부 스크립트가 이미 만든 이름을 타입만 붙여서 프로젝트에 알려줍니다.
02 전역 함수 declare function initializeApp(config) 호출은 전역에서 일어나며 구현은 선언 파일 밖의 스크립트가 제공합니다.
03 Window 속성 interface Window { _paq?: Array<any> } 런타임 값이 window 아래에 붙을 때 전역 객체의 형태를 확장합니다.
04 묶음 유틸 declare namespace MyGlobalUtils 함수와 클래스를 하나의 전역 네임스페이스 아래에서 구조화합니다.
05 모듈과의 경계 declare module "name" import로 불러오는 패키지 이름에 쓰는 문법이므로 전역 스크립트 선언을 감싸는 용도로 쓰지 않습니다.

적용 범위

  • 선언 파일이 프로젝트에 포함되면 해당 이름은 import 없이 전역에서 보입니다.
  • 선언은 타입만 제공하므로 실제 스크립트 로드는 HTML이나 번들 설정이 따로 책임집니다.
  • 전역 이름은 런타임 이름과 철자까지 같아야 합니다.

검증 경계

전역 선언은 편하지만 범위가 넓습니다. 필요한 이름만 좁게 선언하고, import 가능한 라이브러리는 모듈 선언이나 공식 타입 패키지로 분리해야 전역 오염을 줄일 수 있습니다.