AMBIENT MODULE

declare module import 타입 계약

번들러는 이미지, CSS, JSON 같은 파일 import를 빌드 단계에서 URL, 클래스 맵, 데이터 객체 같은 런타임 값으로 변환합니다. TypeScript는 그 결과가 문자열인지, 클래스 맵인지, 컴포넌트인지 모르기 때문에 와일드카드 선언으로 import 결과 타입을 명시합니다.

파일 import와 declare module 타입 계약 흐름 소스 코드의 파일 import는 TypeScript 선언 파일에서 타입을 얻고, 실제 변환은 번들러가 런타임 값으로 처리한다. import asset logo.png / styles.css *.d.ts contract declare module '*.png' value: string TS compiler 타입 오류만 검사 typed import logo: string bundler URL/class/data 변환 선언은 런타임 변환을 만들지 않고, import 결과의 타입 계약만 제공한다
import logo.png, styles.css 같은 파일을 불러온다
.d.ts declare module이 import 결과 타입을 알려준다
compiler TypeScript는 타입 계약만 검사하고 변환은 만들지 않는다
bundler Vite/Webpack/Next.js가 URL, 클래스 맵, 데이터 값으로 바꾼다
*.png

이미지 URL

declare module '*.png' const value: string;

import logo from './logo.png'의 결과를 번들링된 URL 문자열로 취급합니다.

*.svg

컴포넌트 또는 src

ReactComponent export default src

SVGR 설정이 있으면 React 컴포넌트로, 기본 import는 URL 문자열로 쓰는 패턴을 선언할 수 있습니다.

*.css

클래스 맵

const content: {'{ [className: string]: string }'}

CSS Modules처럼 styles.container를 읽을 때 문자열 클래스 이름을 반환 타입으로 고정합니다.

*.json

데이터 값

declare module '*.json' const value: any;

JSON import를 허용하되 실제 프로젝트에서는 응답 schema나 설정 파일 구조에 맞춘 타입으로 좁혀 잘못된 필드 접근을 막습니다.

사용 예시 연결

logo import logo from './logo.png' → logo: string
Icon import Icon from './fallback-image.svg' → 설정에 따라 컴포넌트 또는 src
styles styles.container → "main_container__abc123" 같은 클래스 문자열

핵심은 파일 확장자와 import 결과 타입을 연결하는 것입니다. declare module '*.ext'는 TypeScript가 번들러의 파일 모듈을 이해하게 만드는 얇은 계약입니다.