카카오 지도

[Seon-K]

1. ✨ 설계 배경 및 목적

카카오 지도를 웹 프로젝트에 연동하는 방식은 크게 두 가지가 있습니다.

1. window 객체를 통해 직접 Kakao Maps API를 사용하는 방식
2. react-kakao-maps-sdk와 같은 서드파티 라이브러리를 사용하는 방식

현재 저희 프로젝트에는 직접 window.kakao 객체를 활용하여 지도를 렌더링하는 방식을 채택했으며 두 방식의 차이점과 해당 방식을 채택한 이유는 다음과 같습니다.

비교 항목	react-kakao-maps-sdk 사용	직접 SDK 로드 + DOM API 사용
번들 크기	비교적 큼	가벼움
커스터마이징 자유도	제한적	완전 자유
로딩 제어	내부적으로 처리됨	명시적으로 로직 구성 가능
사용 난이도	쉬움	상대적으로 복잡함
SSR 지원	공식적으로 제한됨	renderToString을 활용하여 수동 구현 가능

• 저희 프로젝트에서는 지도 기능이 단일 페이지에만 사용되며, 마커 + 오버레이 정도의 간단한 기능만 필요합니다.
• 따라서 의존성 최소화, 로드 속도 개선, 사용자 제어 강화를 위해 SDK를 직접 로딩하는 방식으로 구성하였습니다.

참고: react-kakao-maps-sdk는 빠르게 적용 가능하지만, 렌더링 로직이 컴포넌트 단위로 감싸져 있어 유연한 제어가 어려울 수 있다고 합니다.

2. 🧱 구성요소 및 구조

domain/Activity/
            ┗ libs/
                ┗ detail/
                ┗ getLatLngByAddress.ts  // 주소 → 위경도 변환 함수
            ┗ components/
                    ┗ detail/
                          ┣ KaKaoMap.tsx               // 메인 지도 컴포넌트
                          ┗ CustomOverlay.tsx         // 지도 오버레이 컴포넌트

• KaKaoMap.tsx: 핵심 로직이 담긴 컨테이너 컴포넌트
• CustomOverlay.tsx: 지도 위에 표시되는 주소용 말풍선 UI
• getLatLngByAddress.ts: 주소 → 위경도 변환 유틸리티

3. ⚙️ 동작 흐름 요약

👨‍💻 개발자 관점 (컴포넌트 내부 흐름)

1. address prop이 전달됨
2. getLatLngByAddress(address) 호출
   → 주소에 해당하는 위도, 경도를 비동기적으로 가져옴
3. 위도, 경도가 반환되면 KakaoMap 인스턴스를 생성하여 중심 좌표로 설정
4. 해당 좌표에 오버레이(CustomOverlay)를 표시

🙋 사용자 관점 (UI 동작 흐름)

1. 상세 페이지에서 지도가 로드됨
2. 주소 위치가 지도의 중심으로 보여짐
3. 해당 위치에 말풍선 오버레이가 나타남

4. 🔮 설계 의도 및 고려사항

• 로드 제어의 명확성: 스크립트가 로드되지 않았을 경우를 처리하도록 설계
• fallback UI: 에러/로딩 상태에 따른 UI 분기 처리
• 커스터마이징 확장성: 추후 오버레이에 동작을 추가하거나 주소 스타일을 수정할 여지를 고려
• React + Kakao 지도간 연결 지점: renderToString을 활용해 React 컴포넌트를 Kakao Map에서 사용 가능하게 함

4. 🔮 설계 의도 및 고려사항

• 로드 제어의 명확성: 스크립트가 로드되지 않았을 경우를 처리하도록 설계
• fallback UI: 에러/로딩 상태에 따른 UI 분기 처리
• 커스터마이징 확장성: 추후 오버레이에 동작을 추가하거나 지도 스타일을 수정할 여지를 고려
• React + Kakao 지도간 연결 지점: renderToString을 활용해 React 컴포넌트를 Kakao Map에서 사용 가능하게 함

5. 🪄 세부 설명: 주요 훅 / 컴포넌트 / 유틸

🔹 KaKaoMap

• props: address, className
• 상태: isLoading, error, finalAddress
• 역할: 지도 렌더링 및 오류 처리, fallback UI 제공

🔹 CustomOverlay

• props: address
• 역할: 말풍선 형태의 주소 시각화

🔹 getLatLngByAddress

• 역할: Kakao Geocoder API를 통해 주소를 위경도로 변환
• 실패 시 null 반환

🔹 loadKakaoScript

• 동적으로 <script> 태그를 삽입하여 Kakao Map SDK를 비동기 로딩

6. 🧩 사용 예시 및 패턴

<KaKaoMap address="서울특별시 중구 세종대로 110" className="mt-10" />

• address: 지도 중심 위치

• className: Tailwind 클래스 등 외부 스타일 커스터마이징

7. ⚠️ 사용 시 주의사항

• NEXT_PUBLIC_KAKAO_MAP_APP_KEY 환경 변수가 반드시 설정되어 있어야 합니다.
  • env 문서 확인 후 env 파일 최신화를 해주세요!

8. 📎 참고 파일 및 링크

📌 renderToString
React 컴포넌트를 문자열로 렌더링하는 함수입니다. 서버 사이드 렌더링(SSR)에서 주로 사용되지만, 여기서는 **React 컴포넌트를 문자열로 변환 후 외부 라이브러리(Kakao 지도)**에 삽입하기 위해 사용됩니다.

📌 Geocoder
Kakao 지도에서 제공하는 주소 → 좌표 변환 서비스입니다.
addressSearch 메서드를 통해 문자열 주소를 위도/경도 형태로 변환할 수 있습니다. result 배열의 첫 번째 값을 기준으로 좌표를 가져옵니다.

renderToString
카카오지도 API 가이드
Geocoder