🗺️ Next.js + Kakao Map API로 현재 위치 기반 동네 선택 기능 만들기

이번 팀 프로젝트에서 “현재 위치를 기반으로 사용자의 동네를 표시하는 기능”이 필요했다.

마침 지도 기능이 있으면 UX적으로도 좋을 것 같아서, 카카오맵 API를 직접 붙여보기로 했다.

이번 글에서는 모달 컴포넌트부터 LocationModal, 그리고 카카오 지도 API 연동까지 전체 과정을

코드 한 줄 한 줄 뜯어가면서 정리한다.

---

🔍 구현 순서

1. 공통 모달 (Modal.tsx) → 어디서든 재사용 가능한 모달 베이스
2. LocationModal.tsx → “동네 설정”용 모달 UI
3. Kakao Map API 적용 → 지도 띄우기 + 클릭으로 지역명(서울시 동작구) 표시

1) 공통 모달 (Common Modal) — createPortal + SSR 가드

어디서나 재사용 가능한 모달 컨테이너.

핵심 포인트: SSR에서 안전, 포털로 body 최상단에 렌더, 모달 열릴 때만 렌더

코드

// components/common/Modal.tsx
'use client'

import { ComponentPropsWithRef, ReactNode, useEffect, useState } from 'react'
import { createPortal } from 'react-dom'
import { cn } from '@/lib/utils'
import { Card, CardContent, CardFooter, CardHeader } from './Card'

interface ModalProps extends ComponentPropsWithRef<'div'> {
  open: boolean
  onClose: () => void
  children?: ReactNode
  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'
  closeOnBackdrop?: boolean
}

export function Modal({
  open,
  onClose,
  children,
  size = 'md',
  closeOnBackdrop = false,
  className,
  ...props
}: ModalProps) {
  // ✅ SSR 가드: 브라우저에서만 렌더(서버에선 document가 없음)
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])

  // 사이즈 프리셋
  const sizeClasses = {
    sm: 'max-w-sm',
    md: 'max-w-md',
    lg: 'max-w-lg',
    xl: 'max-w-xl',
    '2xl': 'max-w-2xl',
    '3xl': 'max-w-3xl',
    full: 'max-w-full mx-4',
  } as const

  // ✅ 백드롭 클릭 시 닫기 (옵션)
  const handleBackdropClick = (e: React.MouseEvent<HTMLDivElement>) => {
    if (closeOnBackdrop && e.target === e.currentTarget) onClose()
  }

  // ✅ 닫혀 있을 때/SSR일 때는 렌더하지 않음 → 초기 화면 흐려짐 방지
  if (!mounted || !open) return null

  const modalContent = (
    <>
      {/* 백드롭(뒷배경) */}
      <divclassName="fixed inset-0 z-50 bg-background/80 backdrop-blur-sm"
        onClick={handleBackdropClick}
      />
      {/* 중앙 정렬 컨테이너. 여기 "안"에 Card(본문)가 있어야 중앙정렬이 먹음 */}
      <div className="fixed inset-0 z-50 flex items-center justify-center pointer-events-none">
        <CardclassName={cn(
            'relative w-full mx-4 my-8 max-h-[90vh] pointer-events-auto',
            sizeClasses[size],
            className
          )}
          {...props}
        >
          {children}
        </Card>
      </div>
    </>
  )

  // ✅ body 아래로 포털 렌더 → z-index/overflow 간섭 최소화
  return createPortal(modalContent, document.body)
}

export { CardHeader as ModalHeader }
export { CardContent as ModalContent }
export { CardFooter as ModalFooter }

왜 이렇게?

• SSR 가드: Next.js(App Router)는 서버에서 먼저 렌더 → document가 없으므로 mounted 이후에만 렌더.
• Portal: 모달은 대개 최상단(z-50 이상)으로 올라와야 하고, 페이지 레이아웃과 독립되어야 함.
• 닫힐 땐 렌더 X: open={false} 때 백드롭/모달 DOM 자체가 존재하지 않도록 해서, 초기 화면이 흐려지는 문제를 근본 차단.

---

2) LocationModal — 공통 모달에 “동네 설정” UI 얹기

공통 모달은 “그릇”, LocationModal은 “내용물”.

여기서는 헤더 + Kakao 지도 선택기(LocationPicker)를 조립하고, env 키를 하위로 전달합니다.

코드

// components/header/LocationModal.tsx
'use client'

import { MapPinIcon } from 'lucide-react'
import { Modal, ModalHeader, ModalContent } from '@/components/common/Modal'
import LocationPicker from '@/components/location/LocationPicker'

type Props = {
  open: boolean
  onClose: () => void
  onSelect?: (region: string, lat: number, lng: number) => void
}

export default function LocationModal({ open, onClose, onSelect }: Props) {
  // ✅ env에서 카카오 JS 키 읽어서 하위 컴포넌트에 넘김
  const appKey = process.env.NEXT_PUBLIC_KAKAO_JAVASCRIPT_KEY as string

  return (
    <Modal open={open} onClose={onClose} size="md" closeOnBackdrop>
      <ModalHeader className="flex flex-row items-center gap-2 space-y-0">
        <MapPinIcon className="w-5 h-5" />
        <h3 className="text-base leading-none">동네 설정</h3>
      </ModalHeader>

      <ModalContent>
        <LocationPickerappKey={appKey}
          open={open}
          onPick={({ lat, lng, region }) => {
            // 지역명/좌표를 상위로 전달 (ex. 상태 저장, DB 반영)
            onSelect?.(region, lat, lng)
            onClose()
          }}
        />
      </ModalContent>
    </Modal>
  )
}

왜 이렇게?

• env는 사용하는 쪽에서 주입: 훅/컴포넌트 내부에서 process.env를 직접 읽는 대신, prop으로 주입하면 테스트/환경 전환이 쉬워짐.
• UI 레벨 관심사 분리: 모달 컨테이너(공통) ↔️ 위치 설정 도메인(헤더/지도) 구분.

---

3) Kakao Map API 적용 — SDK 로더 훅 + 지도/역지오코딩

이 파트는 2개 파일로 구성합니다.

1. useKakaoLoader.ts: 카카오 지도 SDK 스크립트를 동적으로 로드하고 준비 완료 상태(ready)를 제공.
2. LocationPicker.tsx: 실제 지도를 띄우고, 지도 클릭/현재 위치로 좌표를 받아 “서울시 동작구” 형식의 라벨을 생성.

---

3-1) SDK 로더 훅

// hooks/useKakaoLoader.ts
'use client'

import { useEffect, useState } from 'react'

const KAKAO_SDK_ID = 'kakao-maps-sdk'

export function useKakaoLoader(appKey: string) {
  const [ready, setReady] = useState(false)

  useEffect(() => {
    if (typeof window === 'undefined') return

    // 이미 로드되어 있다면 즉시 OK
    if ((window as any).kakao?.maps) {
      setReady(true)
      return
    }

    // 같은 ID의 스크립트가 있으면 이벤트만 연결 (중복 주입 방지)
    const prev = document.getElementById(KAKAO_SDK_ID) as HTMLScriptElement | null
    if (prev) {
      const onLoad = () => (window as any).kakao.maps.load(() => setReady(true))
      prev.addEventListener('load', onLoad)
      return () => prev.removeEventListener('load', onLoad)
    }

    // 신규 주입
    const script = document.createElement('script')
    script.id = KAKAO_SDK_ID
    script.async = true
    script.src = `https://dapi.kakao.com/v2/maps/sdk.js?appkey=${appKey}&libraries=services&autoload=false`
    script.onload = () => (window as any).kakao.maps.load(() => setReady(true))
    script.onerror = (e) => console.error('[KakaoLoader] script error', e)
    document.head.appendChild(script)
  }, [appKey])

  return ready
}

준비물

• 카카오 개발자 콘솔에서 “카카오맵(지도/로컬)” 제품 활성화
• JavaScript 키 사용 (REST 키 X)
• 플랫폼 도메인 등록: http://localhost:3000 등

타입 경고가 뜨면 한번만 추가:

// types/kakao.maps.d.ts
export {}
declare global { interface Window { kakao: any } }

tsconfig.json → "include": ["next-env.d.ts","src/types/**/*.d.ts","**/*.ts","**/*.tsx"]

---

3-2) LocationPicker — 지도/현재 위치/“서울시 동작구” 라벨

// components/location/LocationPicker.tsx
'use client'

import { useEffect, useRef, useState } from 'react'
import { useKakaoLoader } from '@/hooks/useKakaoLoader'

type Props = {
  appKey: string
  open: boolean
  onPick: (payload: { lat: number; lng: number; region: string }) => void
}

/** 시/도 보정: '서울' → '서울시', '경기' → '경기도', '세종' → '세종특별자치시' */
function formatSido(sido: string) {
  if (/(특별시|광역시|특별자치시|특별자치도|도|시)$/.test(sido)) return sido
  const metro = ['서울', '부산', '대구', '인천', '광주', '대전', '울산', '세종']
  return metro.includes(sido) ? (sido === '세종' ? '세종특별자치시' : `${sido}시`) : `${sido}도`
}

/** H(행정동) 우선 → "서울시 동작구" 형식 라벨 생성 */
function pickGuLabel(res: any[]) {
  const target = res.find((r: any) => r.region_type === 'H') ?? res[0]
  const { region_1depth_name: sidoRaw, region_2depth_name: guRaw } = target
  const sido = formatSido(sidoRaw || '')
  const gu = guRaw || ''
  return gu ? `${sido} ${gu}` : `${sido}`
}

export default function LocationPicker({ appKey, open, onPick }: Props) {
  const ready = useKakaoLoader(appKey)                       // ✅ SDK 준비 상태
  const boxRef = useRef<HTMLDivElement | null>(null)         // ✅ 지도 컨테이너
  const [map, setMap] = useState<any>(null)
  const [marker, setMarker] = useState<any>(null)
  const [label, setLabel] = useState<string>('')

  // 1) 모달 열리고 + SDK 준비되면 지도 생성
  useEffect(() => {
    if (!open || !ready || !boxRef.current || map) return
    const kakao = (window as any).kakao
    const center = new kakao.maps.LatLng(37.5665, 126.9780) // 서울시청
    const _map = new kakao.maps.Map(boxRef.current, { center, level: 5 })
    const _marker = new kakao.maps.Marker({ position: center })
    _marker.setMap(_map)
    setMap(_map)
    setMarker(_marker)
  }, [open, ready, map])

  // 2) 모달이 "열린 후" 레이아웃 보정 (모달 숨김 상태에서 초기화하면 타일이 안 그려짐)
  useEffect(() => {
    if (!open || !map) return
    const id = setTimeout(() => {
      map.relayout()
      map.setCenter(map.getCenter())
    }, 0)
    return () => clearTimeout(id)
  }, [open, map])

  // 3) 지도 클릭 → 좌표 → 역지오코딩 → "서울시 동작구"
  useEffect(() => {
    if (!map || !marker) return
    const kakao = (window as any).kakao
    const geocoder = new kakao.maps.services.Geocoder()

    const clickHandler = (e: any) => {
      const latlng = e.latLng
      marker.setPosition(latlng)
      map.panTo(latlng)
      geocoder.coord2RegionCode(
        latlng.getLng(),
        latlng.getLat(),
        (res: any, status: any) => {
          if (status === kakao.maps.services.Status.OK && res[0]) {
            setLabel(pickGuLabel(res))
          }
        }
      )
    }

    kakao.maps.event.addListener(map, 'click', clickHandler)
    return () => kakao.maps.event.removeListener(map, 'click', clickHandler)
  }, [map, marker])

  // 4) 현재 위치 버튼 (HTTPS 필요 / 로컬 개발은 예외적으로 허용)
  const useCurrentLocation = () => {
    if (!map || !marker) return
    if (!navigator.geolocation) return alert('브라우저에서 위치를 지원하지 않아요.')
    navigator.geolocation.getCurrentPosition(
      ({ coords }) => {
        const kakao = (window as any).kakao
        const geocoder = new kakao.maps.services.Geocoder()
        const latlng = new kakao.maps.LatLng(coords.latitude, coords.longitude)
        marker.setPosition(latlng)
        map.setCenter(latlng)
        geocoder.coord2RegionCode(
          latlng.getLng(),
          latlng.getLat(),
          (res: any, status: any) => {
            if (status === kakao.maps.services.Status.OK && res[0]) {
              setLabel(pickGuLabel(res))
            }
          }
        )
      },
      () => alert('현재 위치 권한을 허용해 주세요.')
    )
  }

  // 5) 상위로 선택 결과 전달
  const confirm = () => {
    if (!marker) return
    const pos = marker.getPosition()
    onPick({ lat: pos.getLat(), lng: pos.getLng(), region: label })
  }

  return (
    <div className="space-y-3">
      {/* 지도는 고정 높이가 꼭 있어야 함. (없으면 보이지 않음) */}
      <div ref={boxRef} className="h-72 w-full rounded-xl border overflow-hidden" />
      <div className="flex items-center justify-between text-sm">
        <div className="text-muted-foreground">
          {label ? `선택된 지역: ${label}` : '지도를 클릭하거나 현재 위치를 사용하세요'}
        </div>
        <div className="flex gap-2">
          <button className="h-9 rounded-md border px-3" onClick={useCurrentLocation}>
            현재 위치
          </button>
          <buttonclassName="h-9 rounded-md bg-primary px-3 text-primary-foreground disabled:opacity-50"
            disabled={!label}
            onClick={confirm}
          >
            선택
          </button>
        </div>
      </div>
    </div>
  )
}

왜 이렇게?

• 모달이 열린 뒤 초기화 + relayout: 숨겨진 컨테이너에서 지도를 만들면 타일이 안 그려지는 이슈를 해결.
• 구/군 단위 라벨: coord2RegionCode 응답에서 region_2depth_name(구/군) + region_1depth_name(시/도) 조합.
• 시/도 보정: ‘서울’ → ‘서울시’, ‘경기’ → ‘경기도’ 등 가독성 개선.

---

환경 변수 / 콘솔 설정 (한 번만)

.env.local

NEXT_PUBLIC_KAKAO_JAVASCRIPT_KEY=카카오_JavaScript_키

• dev 서버 재시작 필수.
• 카카오 개발자 콘솔
  • 제품 설정 → 카카오맵(지도/로컬) 활성화(OPEN_MAP_AND_LOCAL)
  • 앱 설정 → 플랫폼 → Web → 사이트 도메인 등록 (http://localhost:3000 등)
  • JavaScript 키 사용 (REST 키 X)

전역 타입 선언(선택):

// types/kakao.maps.d.ts
export {}
declare global { interface Window { kakao: any } }

---

마무리 — 흐름 요약

1. 공통 모달: createPortal과 SSR 가드로 어디서든 안전하게 띄움
2. LocationModal: 공통 모달에 “동네 설정” UI를 얹고, env 키를 하위로 전달
3. Kakao Map API:
   • 로더 훅으로 SDK 한 번만 로드
   • 모달 열릴 때 지도 초기화 + relayout()
   • 지도 클릭/현재 위치 → 역지오코딩 → “서울시 동작구” 라벨 → 상위로 전달