카카오맵 API 타입스크립트로 사용하기 (kakao.maps.d.ts로 Type 적용)

카카오맵을 사용한 프로젝트를 진행하고 있는데, 타입 정의 문제가 발생했다.

처음에는 kakao 객체 존재 여부를 TS에서 인식하지 못하기 때문에, 객체가 window에 있다고 선언했다.

declare global {
  interface Window {
    kakao: any;
  }
}

 

카카오에서도 이렇게 선언하라고 했는데, (https://devtalk.kakao.com/t/typescript/126917/2)

개발 과정에서는 문제 없이 실행되더라도, 문제는 빌드였다.

빌드 과정에서 any 타입에 모든 빨간줄을,,, ㅠㅠ

 

카카오에서는 API 타입을 따로 제공하지 않았다 😱

그래서 임시로 장소 결과 객체 타입을 정의했으나

export type KakaoPlace = {
  address_name: string; // 지번 주소
  category_group_code: string; // 카테고리 코드 (ex. CE7: 카페)
  category_group_name: string; // 카테고리 그룹명 (ex. 카페)
  category_name: string; // 상세 카테고리 (ex. 음식점 > 카페)
  distance: string; // 기준 좌표와의 거리 (미터 단위)
  id: string; // 장소 ID
  phone: string; // 전화번호 (없으면 빈 문자열)
  place_name: string; // 장소명
  place_url: string; // 카카오맵 URL
  road_address_name: string; // 도로명 주소
  x: string; // 경도 (longitude)
  y: string; // 위도 (latitude)
};

 

각 객체마다 사용하는 메소드나 프로퍼티를 모두 정의해야하나 좌절하던 중

다행히 카카오맵 타입 패키지를 발견했다!!! (나의 구세주..)

GitHub - JaeSeoKim/kakao.maps.d.ts: TypeScript Definitions for kakao.maps.* (Kakao(구 Daum) 지도 Web API)

 

설치를 했으나 이후 구체적인 사용 방법이 없어서 또 해멨다.

이걸 사용하는 다른 프로젝트에서는 폴더에 있는 파일을 다운로드 해서 types/에 따로 넣어놓는 프로젝트도 있었다.

나는 추가적인 정보가 없어서 패키지를 그대로 사용했다.

---

[ kakao.mpas.d.ts 를 프로젝트에 적용하는 방법 ]

1. 먼저 src/types/global.d.ts 를 작성한다.

중요한 건 kakao 타입을 불러와야한다!! 🌟🌟

그냥 쓰면 사용하는 곳에서 Cannot find namespace 'kakao'.ts 이라고 뜬다

import { kakao } from 'kakao.maps.d.ts';
declare global {
  interface Window {
    kakao: typeof kakao;
  }
}

export {};

 

2. tsconfig.json를 수정한다.

"types" : 어떤 타입을 사용할 지 명시적으로 지정하는 것으로, 다운받은 패키지를 불러온다.

"typeRoots" : 타입 파일을 검색할 경로를 지정하여, 해당 경로에 있는 타입 정의 파일을 검색해서 TS가 자동으로 인식할 수 있도록 한다.

"compilerOptions": {
    ...
    "types": ["kakao.maps.d.ts"],
    "typeRoots": ["./node_modules/@types", "./src/types"]
}

 

3. 기존 카카오맵 api 객체들을 사용하는 곳에 적용한다.

나는 지도 관련 객체들을 ref로 관리했는데, 아래와 같이 타입을 설정하면 된다.

const mapRef = useRef<kakao.maps.Map | null>(null);
const placeRef = useRef<kakao.maps.services.Places | null>(null);
const geoCoderRef = useRef<kakao.maps.services.Geocoder | null>(null);
const currentLocationRef = useRef<{ lat: number; lon: number } | null>(null);

 

메소드를 사용하는 곳에서는 이런식으로 정의된 타입을 사용했다.

const searchByKeyword = (result: kakao.maps.services.PlacesSearchResult, status: string) => {
	...
}

---

빌드 성공!!! ✨✨