TypeScript: 'Property does not exist on type Window' 전역 객체 확장 및 global.d.ts 선언 병합 해결법

TypeScript window 객체 속성 에러 및 global.d.ts 확장 가이드
3초 요약: 이렇게 고치세요
  • 원인: 타입스크립트가 window 타입을 브라우저 표준 사양으로 고정해둬서, 외부 스크립트가 주입한 window.kakao 같은 커스텀 속성을 모르는 속성이라며 막음
  • 해결: 자주 쓰는 SDK는 global.d.ts에 선언 병합 / 1회성이면 (window as any) 단언 / 메이저 도구는 @types/ 패키지 설치
  • 주의: 카카오맵·GTM처럼 <script> 태그로 직접 로드하는 외부 SDK를 쓸 때 특히 자주 마주치는 에러
declare global { interface Window { kakao: any; } }
export {};
↓ 왜 이런 에러가 나는지 원리 보기

카카오 로그인이나 GTM처럼 <script> 태그로 불러오는 외부 SDK를 쓰다 보면, 자바스크립트에서는 문제없던 코드가 TypeScript에서 'Property does not exist on type Window' 에러를 내는 경우가 있습니다. window 객체에 전역 스크립트가 주입한 커스텀 속성을 안전하게 다루는 방법 세 가지를 정리합니다.

왜 'does not exist on type window' 에러가 발생하는가

타입스크립트는 브라우저 웹 API 사양에 근거해 기본 window 객체의 타입을 고정해 두었습니다. 이 때문에 런타임에 외부 스크립트가 강제로 주입한 커스텀 객체(예: window.kakao 또는 window.daum)가 들어오더라도, 컴파일러는 "그런 객체는 공식 사양에 존재하지 않는다"며 즉각 컴파일 에러를 일으키는 것입니다. 자바스크립트의 동적 자유도와 타입스크립트의 정적 엄격성 사이에서 흔히 일어나는 충돌 양상입니다. 카카오맵이나 GTM처럼 <script> 태그로 직접 로드하는 외부 SDK를 쓸 때 특히 자주 마주치는 에러입니다.

기본 Window 타입은 브라우저 표준 DOM 사양에 고정되어 있어 window.kakao처럼 외부 SDK가 주입한 속성을 참조하면 존재하지 않는 속성이라며 에러를 냅니다. global.d.ts 같은 전역 확장 파일을 만들어 선언 병합(Declaration Merging)을 적용하면 이런 속성도 기본 Window 타입에 안전하게 합쳐져 에러 없이 사용할 수 있습니다.

Window 타입을 확장하는 3가지 우회 전술

방법 A: global.d.ts 파일로 전역 인터페이스 선언 추가 (가장 권장)

가장 정석적인 해결법입니다. 전역 타입 정의용 폴더/파일을 생성하여 타입스크립트의 선언 병합(Declaration Merging) 특징을 활용해 Window 규격서 자체를 확장합니다. global.d.ts 파일을 만드신 후 아래 코드를 기입하세요. 

declare global {
  interface Window {
    // 1. 외부 카카오 SDK용 타입 추가 (임시 any 설정)
    kakao: any;

    // 2. 구글 애널리틱스 로그 수집 레이어용 타입 추가
    dataLayer: any[];
  }
}

// 이 파일이 전역 모듈임을 타입스크립트 컴파일러에 인지시키기 위해 빈 export 추가
export {};

방법 B: 타입 단언(Type Assertion - any 우회)

임시로 빠르게 작업을 마쳐야 하거나, 1회용 컴포넌트 내부에서만 짧게 쓰고 말아야 할 때 유용한 일회용 우회법입니다. 

// window 객체를 강제로 any 타입으로 형변환하여 컴파일 가드를 우회합니다.
const kakaoSdk = (window as any).kakao;

if (kakaoSdk) {
  kakaoSdk.maps.load(() => {
    console.log("지도 로드 성공");
  });
}

방법 C: 외부 타입 라이브러리(@types/... ) 공식 패키지 설치

만약 연동하려는 오픈소스 라이브러리가 전 세계적으로 많이 쓰이는 것이라면, 굳이 직접 타이핑을 작성할 필요 없이 개발자 커뮤니티가 기정의해 놓은 공식 패키지를 DevDependency로 깔아서 통과하는 것이 좋습니다. 

# 예시: 구글 애널리틱스(gtag)용 전역 타입 패키지 설치
npm install --save-dev @types/gtag.js

카카오 로그인을 붙이는 작업에서 window.Kakao를 아무 데서나 (window as any)로 눌러쓰다가, 나중에 오타로 window.Kako라고 잘못 쓴 곳을 컴파일러가 전혀 못 잡아준 적이 있습니다. 그때부터는 처음 SDK를 붙이는 시점에 global.d.ts부터 만들어두는 쪽으로 습관을 바꿨습니다.

요약: 전역 Window 객체 확장 전략 매트릭스

글로벌 객체 오염을 방지하고 안전하게 타입을 병합하는 우회 전략 테이블입니다.

상황 원인 및 리스크 추천 해결 기술
반복적인 타사 SDK 연동 (카카오 등) 여러 파일에서 window 속성 참조 시 중복 빌드 에러 노출 global.d.ts 선언 병합 확장
임시 기능 개발 및 1회성 스크립트 global.d.ts 파일 세팅을 위한 불필요한 공수 최소화 시 (window as any) 임시 단언
구글 태그, 유튜브 API 등 메이저 도구 검증되지 않은 임의의 type 사용으로 타입 안정성 저하 우려 @types/ 전용 패키지 추가
공식 참고 레퍼런스

타입스크립트의 선언 병합 아키텍처에 대한 공식 문서는 아래에서 확인할 수 있습니다.

호마다의 웹개발 팁

실무에서는 자주 쓰는 SDK라면 global.d.ts로 타입을 한 번 정의해두고, 1회성 스크립트라면 (window as any)로 짧게 우회하는 식으로 상황에 따라 나눠 쓰는 편이 낫습니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

TypeScript: Unknown vs Any 타입 차이점과 안전한 타입 가드(Type Guard)

이미지
3초 요약: 이렇게 고치세요 원인: any 는 타입 검사 자체를 포기하는 선언이라, 잘못된 속성 접근이 컴파일 시점엔 통과했다가 런타임에 터짐 해결: 외부 API 응답처럼 타입을 확신할 수 없는 데이터는 unknown 으로 받고, data is T 형태의 타입 가드로 검증한 뒤에만 사용 주의: 타입 가드 내부에서 as Record<string, unknown> 같은 임시 캐스팅으로 속성을 하나씩 검사하는 절차를 생략하면 unknown 을 쓰는 의미가 없어짐 function isUserProfile(data: unknown): data is UserProfile { ... } ↓ 왜 any가 위험한지 원리 보기 실무에서 대규모 TypeScript 프로젝트를 마이그레이션하거나, 외부 API 또는 레거시 라이브러리를 통합하다 보면 필연적으로 "타입을 확신할 수 없는 데이터"를 다루게 됩니다. 이때 많은 개발자들이 급한 마음에 가장 손쉬운 탈출구인 any 를 사용하곤 합니다. 하지만 이는 TypeScript의 가장 큰 무기인 타입 안정성을 스스로 내려놓는 행위이자, 미래의 나에게 런타임 에러라는 시한폭탄을 던지는 것과 같습니다. any 가 왜 위험한지, TypeScript 3.0에서 도입된 unknown 이 이를 어떻게 막아주는지, 그리고 실무에서 바로 써먹을 수 있는 사용자 정의 타입 가드(User-Defined Type Guards) 작성 패턴을 정리합니다. any의 위험성과 unknown의 등장 프로덕션 환경에서 발생한 실제 에러 로그를 분석해 보면, 꽤 많은 비율이 TypeError: Cannot read properties of undefined 에서 시작합니다. 그리고 그 이면에는 높은 확률로 any 타입이 자리 잡고 있죠. any: 타입...
자세한 내용 보기

Next.js 하이드레이션 오류 원인과 해결법 완벽 정리

이미지
3초 요약: 이렇게 고치세요 원인: 서버가 렌더링한 초기 HTML과 브라우저가 처음 그린 HTML 구조가 서로 달라서 발생 — React는 둘이 같을 거라 믿고 결합을 시도하다가 실패함 해결: 잘못된 태그 중첩이면 마크업 수정 / window · localStorage 참조면 useEffect 로 이동 / 시간·랜덤값처럼 매번 달라지는 값이면 ssr: false 로 분리 주의: suppressHydrationWarning 은 경고를 숨길 뿐 원인을 고치는 게 아니라서, 불가피한 텍스트 불일치(타임스탬프 등)에만 제한적으로 써야 함 const [isMounted, setIsMounted] = useState(false); useEffect(() => setIsMounted(true), []); if (!isMounted) return null; // 서버와 첫 클라이언트 렌더는 항상 동일하게 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js를 쓰다 보면 콘솔에 "Hydration failed because the initial UI does not match..."라는 붉은 에러가 뜰 때가 있습니다. 빌드는 멀쩡히 끝났는데 화면이 그려진 직후에 갑자기 나는 에러라서 처음 보면 당황스럽습니다. 원인은 대부분 서버와 클라이언트가 그린 첫 화면이 미묘하게 다르기 때문이고, 패턴이 정해져 있어서 하나씩 짚어보면 금방 잡힙니다. 하이드레이션(Hydration), 정확히 어떤 과정인가 Next.js의 핵심 기능은 서버 사이드 렌더링(SSR)입니다. 서버는 먼저 사용자에게 정적인 HTML 뼈대를 빠르게 그려서 브라우저에 내려보내 줍니다. 그 후, 브라우저(클라이언트)가 이 정적인 HTML 위에 React의 자바스크립트 코드와 이벤트 리스너를 결합하여 ...
자세한 내용 보기

Next.js App Router에서 getServerSideProps 대체 및 데이터 페칭법

이미지
3초 요약: 이렇게 고치세요 원인: App Router는 서버 컴포넌트에서 직접 async/await를 쓸 수 있어 getServerSideProps / getStaticProps 가 아예 없어짐 해결: 빌드 시 캐싱(SSG) → 기본 fetch / 매 요청 최신화(SSR) → { cache: 'no-store' } / 주기 갱신(ISR) → { next: { revalidate: N } } 주의: getServerSideProps 안에 있던 인증 체크 로직은 이제 컴포넌트 함수 내부나 미들웨어로 옮겨야 함 const res = await fetch(url, { cache: 'no-store' }); // SSR과 동일하게 매번 재요청 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js 13 이상에서 App Router가 표준이 되면서, Pages Router에서 쓰던 getServerSideProps 와 getStaticProps 가 더 이상 동작하지 않습니다. 두 함수가 사라진 설계적 이유와, 이를 대체하는 데이터 패칭 방식을 정리했습니다. 왜 getServerSideProps와 getStaticProps가 사라졌을까 과거 Next.js는 페이지 컴포넌트 내부에서만 특정 정적 함수( getServerSideProps 등)를 실행하여 데이터를 미리 받아온 뒤, 이를 컴포넌트의 props 로 넘겨주는 복잡한 직렬화 구조를 가졌습니다. 이로 인해 컴포넌트 간 깊이가 깊어지면 'Props Drilling(프로퍼티 대물림)'이 심해져 코드 관리가 몹시 까다로웠습니다. App Router 환경에서는 서버 컴포넌트(Server Component)가 표준이 됨에 따라 컴포넌트 내에서 직접 비동기 함수(async/await)를 작성할 수 있게 되었습...
자세한 내용 보기