앰비언트 선언: 외부 환경의 계약을 좁게 보충하기

"declare는 없는 값을 만드는 주문이 아니라, 다른 곳에 실제로 있다고 컴파일러에게 알리는 약속이야."

앰비언트 문맥의 의미

declare const BUILD_ID: string이나 declare module 'legacy-lib'는 구현이 이 파일 밖에 존재한다고 알린다. 출력 JavaScript는 생기지 않으므로 실제 값이나 모듈이 없다면 실행 중에 그대로 실패해.

전역 변수, 빌드 도구가 주입하는 값, 타입이 없는 모듈을 설명할 때 유용하지만 범위를 넓게 잡으면 모든 파일이 그 이름을 당연히 존재한다고 믿게 돼. 가능하면 모듈 범위의 선언과 명시적 import를 선호해.

모듈 선언과 모듈 보강

새로운 declare module 'x' { ... }는 해당 모듈의 공개 표면을 설명할 수 있어. 이미 타입이 있는 모듈에 멤버를 더하는 모듈 보강은 원래 선언과 합쳐져. 플러그인이 프레임워크 타입을 확장하는 경우가 대표적이지.

보강은 런타임 구현도 실제로 추가했을 때만 맞아. 타입에 메서드만 보태고 초기화 코드를 불러오지 않으면 존재하지 않는 멤버를 안전하다고 속이는 결과가 돼.

와일드카드 모듈과 전역 보강

declare module '*.css'나 declare module '*.png'처럼 패턴을 선언하면 번들러가 처리하는 자산 import의 타입을 설명할 수 있어. declare global 블록은 Window 같은 전역 인터페이스를 보강해. Vite 같은 현대 도구가 이미 제공하는 선언과 겹치지 않는지 먼저 확인해야 해.

declare module의 세 가지 모양

declare module 'x'는 모듈 전체를 any로 두는 축약형, 내보내기 목록을 넣은 블록은 실제 공개 모양을 설명하는 선언, 이미 타입이 있는 모듈을 다시 여는 블록은 보강이야. 보강 안의 interface는 기존 interface와 선언 병합되어 새 멤버를 더해.

앰비언트 선언은 외부 현실을 좁게 번역하는 경계야. 컴파일러를 조용하게 만드는 데 쓰지 말고, 실제 런타임 증거와 함께 유지해.

Code

Ambient 선언 — wildcard, augment, global·typescript

// globals.d.ts — bundler-aware import 용 wildcard module 선언.
declare module '*.css' {
  const content: { [className: string]: string };
  export default content;
}

declare module '*.svg' {
  const url: string;
  export default url;
}

// 이제 이 import 들이 compile:
import styles from './app.module.css';   // styles: { [className: string]: string }
import logo from './logo.svg';            // logo: string

// 기존 library 타입 augment.
declare module 'react' {
  interface CSSProperties {
    '--custom-var'?: string;             // style prop 에 CSS 커스텀 property 허용
  }
}

// Global augment.
declare global {
  interface Window {
    __APP_VERSION__: string;
  }
}

window.__APP_VERSION__;   // ✅ 타입 붙음

Exercise

PNG를 URL 문자열로, JSON을 객체로 가져오는 와일드카드 모듈 선언을 만들어. 현재 번들러가 이미 제공하는 선언과 겹치지 않는지도 확인해.

Hint

현대 번들러는 이미지와 스타일 같은 자산 import를 위한 앰비언트 선언을 제공하기도 해. Vite의 클라이언트 선언에서 어떤 와일드카드 모듈을 정의하는지 살펴봐.

앰비언트 문맥의 의미

모듈 선언과 모듈 보강

와일드카드 모듈과 전역 보강

declare module의 세 가지 모양

Code

External links

Exercise

Progress

댓글 0