Next.js/Remix SSR에서 카카오 API로 주소를 위도 경도 값으로 변환하는 법 (+하이드레이션 문제 해결)

주소를 가지고 지도에 위치를 찍어주어야 할 일이 있었습니다.

카카오 지도 API에서 주소를 위도 경도로 변환하는 기능을 제공해서 이용하기로 했는데요.

카카오 지도 API를 이용하려면 일단 Kakao Map SDK를 External Script로 불러와야 합니다. 다시 말해서 HTML에 아래 스크립트 태그를 넣어주어야 해요.

<script src={`//dapi.kakao.com/v2/maps/sdk.js?appkey=${KAKAO_JAVASCRIPT_KEY}&libraries=services`} />

하지만 Next.js나 Remix 같은 SSR 환경에서 해당 스크립트 태그를 넣게 되면 스크린샷처럼 오류가 발생합니다. 하이드레이션(Hydration) 오류죠.

하이드레이션 오류는 서버측에서 HTML을 렌더링한 결과와 클라이언트측에서 렌더링한 결과가 다를 때 발생하는 문제입니다. 이러한 문제가 발생한 원인은 스크립트 태그로 불러온 카카오 지도 SDK 코드에 있습니다.

카카오 지도 SDK는 자동으로 추가 코드를 로드하면서 document.write 함수를 사용합니다. document.write 함수가 DOM을 조작하면서 서버측 렌더링 결과와 클라이언트측 렌더링 결과가 달라지는 것이죠. 이 문제는 카카오 Developers Devtalk에도 여러 번 언급되어 있습니다.

좌우지간 카카오 Developers에서 내놓은 해결책은 카카오 지도 SDK를 동적으로 로드하는 방법입니다. 자동으로 추가 코드를 로드하게끔 내버려두지 않고서 말이죠. 기존에 SDK를 불러오는 주소에 autoload=false를 쿼리 파라미터로 붙여주면 되겠습니다.

<script src={`//dapi.kakao.com/v2/maps/sdk.js?appkey=${KAKAO_JAVASCRIPT_KEY}&libraries=services&autoload=false`} />

이렇게 하면 카카오 지도 SDK가 더 이상 document.write 함수를 포함한 추가 코드를 자동으로 로드하지 않습니다. 그리고 명시적으로 load 함수를 실행했을 때에만 필요한 내용을 불러옵니다. 사용하는 방법은 다음과 같습니다.

const search = (query: string) => { 
  kakao.maps.load(() => {
    const geocoder = new kakao.maps.services.Geocoder();

    geocoder.addressSearch(query, (result, status) => {
      if (status === kakao.maps.services.Status.OK) {
        console.log(result[0]);
      }
    });
  });
}

이렇게 하면 주소를 좌표로 변환할 수 있습니다. load 함수 콜백을 받기 전에는 kakao.maps.services 객체가 존재하지 않으니 주의해 주세요.