react-naver-maps

네이버 지도 API v3를 React에서 쉽게 사용할 수 있도록 만든 라이브러리입니다. 공식 API 문서는 https://navermaps.github.io/maps.js.ncp/docs/index.html 를 참고하세요.

설치

npm install @rousen/react-naver-maps
# 또는
yarn add @rousen/react-naver-maps
# 또는
pnpm add @rousen/react-naver-maps

TypeScript에서 naver.maps.* 전역 타입을 쓰려면 @types/navermaps를 개발 의존성으로 추가하세요.

npm install -D @types/navermaps
# 또는
yarn add -D @types/navermaps
# 또는
pnpm add -D @types/navermaps

빠른 시작

import { Map, Marker } from "@rousen/react-naver-maps";

function App() {
  return (
    <Map ncpKeyId="your-ncp-key-id">
      <Marker position={{ x: 127.0276, y: 37.4979 }} />
    </Map>
  );
}

기본적으로 GL 서브모듈을 포함해 로드하며, WebGL 렌더링을 사용합니다. 필요 시 disableGL prop으로 옵트아웃할 수 있습니다.

더 자세한 사용법과 API 문서는 문서 사이트를 참고하세요.

개발

의존성 설치

npm install

개발 모드 실행

npm run dev

빌드

npm run build

타입 체크

npm run type-check

린트

npm run lint

문서

상세한 사용법, API 문서, 예제는 문서 사이트에서 확인할 수 있습니다.

주요 기능

• 🗺️ 네이버 지도 API를 React 컴포넌트로 쉽게 사용
• 📍 Marker, Overlay, Polygon, Polyline 등 다양한 오버레이 지원
• 🎯 TypeScript로 작성되어 완전한 타입 정의 제공
• 🔄 네이버 맵스 SDK 자동 로드
• 🎨 React 컴포넌트를 지도 오버레이로 사용 가능
• 📦 트리 쉐이킹 지원
• 🔌 GL 기본 활성(실패 시 자동 non-GL 폴백), Traffic, Transit 등 서브모듈 지원
• ⚡ 풍부한 이벤트 핸들러 지원
• ♻️ reuseMap으로 동일 id 지도 인스턴스 재사용 지원

호환성

이 라이브러리는 다음 환경에서 테스트되었습니다:

• ✅ Vite - 완전 지원
• ✅ Webpack 5 - 완전 지원
• ✅ Next.js - 완전 지원
• ✅ Create React App - 완전 지원
• ✅ TypeScript - 타입 정의 포함
• ✅ ESM & CommonJS - 양쪽 모두 지원
• ✅ 트리 쉐이킹 - 지원

요구사항

• React >= 16.8.0 (Hooks 지원 필요)
• React DOM >= 16.8.0
• 네이버 클라우드 플랫폼(NCP) 클라이언트 ID

라이선스

MIT