kmp-naver-map
Declarative Compose wrapper for Naver Map SDK with overlay DSL (markers, polylines, polygons), camera animations/fitBounds, location tracking, UI controls, night/indoor modes, and Gradle plugin.
네이버 지도 SDK를 Compose Multiplatform에서 선언적으로 사용할 수 있는 라이브러리입니다.
A declarative Naver Map SDK wrapper for Compose Multiplatform (Android & iOS).
-
Overlay DSL —
NaverMap { }스코프 내에서 Marker, Polyline, Polygon, Circle, Path, ArrowheadPath, InfoWindow를 선언적으로 추가 -
Camera Control —
MapEffect를 통한 카메라 애니메이션,fitBounds, 줌 제한 설정 -
Location Tracking —
LocationTrackingMode를 통한 사용자 위치 추적 통합 - MapUiSettings — 줌 버튼, 나침반, 스케일 바, 레이어 그룹 등 UI 요소 제어
- Night Mode & Indoor — 야간 모드, 실내 지도 지원
- Gradle Plugin — 저장소 설정과 의존성을 자동 관리하는 Gradle 플러그인 제공
**사용하려는 모듈(예: composeApp)**의 build.gradle.kts에 플러그인을 추가하세요. 플러그인을 적용하면 네이버 지도 저장소 설정과 라이브러리 의존성이 자동으로 추가됩니다.
// composeApp/build.gradle.kts 또는 shared/build.gradle.kts
plugins {
id("io.github.kmp-naver-map") version "1.0.2"
}
// (선택 사항) 라이브러리 버전을 직접 지정하고 싶은 경우
naverMapCompose {
version.set("1.0.2")
}iOS에서 지도를 정상적으로 표시하려면 네이버 지도 SDK(NMapsMap) 의존성이 필요합니다. 자세한 내용은 Kotlin Multiplatform CocoaPods 공식 문서를 참조하세요.
Kotlin Multiplatform의 cocoapods 플러그인을 사용 중이라면 아래와 같이 추가하세요.
kotlin {
cocoapods {
ios.deploymentTarget = "13.0"
pod("NMapsMap") {
version = "3.23.1"
}
}
}기존 iOS 프로젝트 형식을 유지하고 싶다면 iosApp/Podfile에 다음을 추가하세요.
target 'iosApp' do
use_frameworks!
pod 'NMapsMap', '3.23.1'
endNaverMapSdkProvider로 SDK를 초기화하고, NaverMap 컴포저블로 지도를 표시합니다.
import io.github.kmp.maps.naver.compose.NaverMapSdkProvider
import io.github.kmp.maps.naver.compose.ui.NaverMap
import io.github.kmp.maps.naver.compose.model.LatLng
import io.github.kmp.maps.naver.compose.state.rememberMarkerState
@Composable
fun App() {
NaverMapSdkProvider(clientId = "YOUR_CLIENT_ID") {
NaverMap(modifier = Modifier.fillMaxSize()) {
Marker(
state = rememberMarkerState(position = LatLng(37.566, 126.978)),
caption = "서울시청"
)
}
}
}NaverMap {
// 방법 1: MarkerState 사용 (위치 변경 가능)
val markerState = rememberMarkerState(position = LatLng(37.566, 126.978))
Marker(state = markerState, caption = "서울시청")
// 방법 2: 위치 직접 지정
Marker(position = LatLng(37.551, 126.988), caption = "남산타워")
}MapEffect를 사용하면 지도 준비 후 NaverMapState에 접근하여 카메라를 제어할 수 있습니다.
NaverMap {
MapEffect(selectedPlace) {
animateCamera(
position = CameraPosition(target = selectedPlace.latLng, zoom = 14.0),
durationMs = 1000
)
}
}| 증상 | 해결 방법 |
|---|---|
| 지도가 표시되지 않음 |
NaverMapSdkProvider가 NaverMap을 감싸고 있는지, Client ID가 올바른지 확인하세요. |
| iOS에서 빌드 오류 |
pod install 실행 후 .xcworkspace로 열어야 합니다. cocoapods 플러그인 사용 시 generateComposeResClass 태스크 관련 오류가 나면 Gradle 버전을 확인하세요. |
Could not resolve 의존성 오류 |
Gradle 플러그인 사용 시 네이버 저장소가 자동 추가됩니다. 수동 설정 시 https://repository.map.naver.com/archive/maven을 추가하세요. |
기여는 언제나 환영합니다! 자세한 내용은 CONTRIBUTING.md를 참조하세요.
본 라이브러리는 Apache License 2.0을 따릅니다.
Copyright 2026 Jun Cho
네이버 지도 SDK를 Compose Multiplatform에서 선언적으로 사용할 수 있는 라이브러리입니다.
A declarative Naver Map SDK wrapper for Compose Multiplatform (Android & iOS).
-
Overlay DSL —
NaverMap { }스코프 내에서 Marker, Polyline, Polygon, Circle, Path, ArrowheadPath, InfoWindow를 선언적으로 추가 -
Camera Control —
MapEffect를 통한 카메라 애니메이션,fitBounds, 줌 제한 설정 -
Location Tracking —
LocationTrackingMode를 통한 사용자 위치 추적 통합 - MapUiSettings — 줌 버튼, 나침반, 스케일 바, 레이어 그룹 등 UI 요소 제어
- Night Mode & Indoor — 야간 모드, 실내 지도 지원
- Gradle Plugin — 저장소 설정과 의존성을 자동 관리하는 Gradle 플러그인 제공
**사용하려는 모듈(예: composeApp)**의 build.gradle.kts에 플러그인을 추가하세요. 플러그인을 적용하면 네이버 지도 저장소 설정과 라이브러리 의존성이 자동으로 추가됩니다.
// composeApp/build.gradle.kts 또는 shared/build.gradle.kts
plugins {
id("io.github.kmp-naver-map") version "1.0.2"
}
// (선택 사항) 라이브러리 버전을 직접 지정하고 싶은 경우
naverMapCompose {
version.set("1.0.2")
}iOS에서 지도를 정상적으로 표시하려면 네이버 지도 SDK(NMapsMap) 의존성이 필요합니다. 자세한 내용은 Kotlin Multiplatform CocoaPods 공식 문서를 참조하세요.
Kotlin Multiplatform의 cocoapods 플러그인을 사용 중이라면 아래와 같이 추가하세요.
kotlin {
cocoapods {
ios.deploymentTarget = "13.0"
pod("NMapsMap") {
version = "3.23.1"
}
}
}기존 iOS 프로젝트 형식을 유지하고 싶다면 iosApp/Podfile에 다음을 추가하세요.
target 'iosApp' do
use_frameworks!
pod 'NMapsMap', '3.23.1'
endNaverMapSdkProvider로 SDK를 초기화하고, NaverMap 컴포저블로 지도를 표시합니다.
import io.github.kmp.maps.naver.compose.NaverMapSdkProvider
import io.github.kmp.maps.naver.compose.ui.NaverMap
import io.github.kmp.maps.naver.compose.model.LatLng
import io.github.kmp.maps.naver.compose.state.rememberMarkerState
@Composable
fun App() {
NaverMapSdkProvider(clientId = "YOUR_CLIENT_ID") {
NaverMap(modifier = Modifier.fillMaxSize()) {
Marker(
state = rememberMarkerState(position = LatLng(37.566, 126.978)),
caption = "서울시청"
)
}
}
}NaverMap {
// 방법 1: MarkerState 사용 (위치 변경 가능)
val markerState = rememberMarkerState(position = LatLng(37.566, 126.978))
Marker(state = markerState, caption = "서울시청")
// 방법 2: 위치 직접 지정
Marker(position = LatLng(37.551, 126.988), caption = "남산타워")
}MapEffect를 사용하면 지도 준비 후 NaverMapState에 접근하여 카메라를 제어할 수 있습니다.
NaverMap {
MapEffect(selectedPlace) {
animateCamera(
position = CameraPosition(target = selectedPlace.latLng, zoom = 14.0),
durationMs = 1000
)
}
}| 증상 | 해결 방법 |
|---|---|
| 지도가 표시되지 않음 |
NaverMapSdkProvider가 NaverMap을 감싸고 있는지, Client ID가 올바른지 확인하세요. |
| iOS에서 빌드 오류 |
pod install 실행 후 .xcworkspace로 열어야 합니다. cocoapods 플러그인 사용 시 generateComposeResClass 태스크 관련 오류가 나면 Gradle 버전을 확인하세요. |
Could not resolve 의존성 오류 |
Gradle 플러그인 사용 시 네이버 저장소가 자동 추가됩니다. 수동 설정 시 https://repository.map.naver.com/archive/maven을 추가하세요. |
기여는 언제나 환영합니다! 자세한 내용은 CONTRIBUTING.md를 참조하세요.
본 라이브러리는 Apache License 2.0을 따릅니다.
Copyright 2026 Jun Cho