# react-naver-maps

[![npm version](https://img.shields.io/npm/v/%40rousen%2Freact-naver-maps.svg)](https://www.npmjs.com/package/@rousen/react-naver-maps)
[![npm downloads](https://img.shields.io/npm/dm/%40rousen%2Freact-naver-maps.svg)](https://www.npmjs.com/package/@rousen/react-naver-maps)
[![Publish](https://github.com/knsan189/react-naver-maps/actions/workflows/publish.yml/badge.svg)](https://github.com/knsan189/react-naver-maps/actions/workflows/publish.yml)
[![GitHub stars](https://img.shields.io/github/stars/knsan189/react-naver-maps?style=flat)](https://github.com/knsan189/react-naver-maps)

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

- [npm 패키지](https://www.npmjs.com/package/@rousen/react-naver-maps)
- [GitHub 저장소](https://github.com/knsan189/react-naver-maps)
- [문서 사이트](https://knsan189.github.io/react-naver-maps)
- [버그 및 기능 제안](https://github.com/knsan189/react-naver-maps/issues)

## 설치

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

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

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

## 빠른 시작

```tsx
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 문서는 [문서 사이트](https://knsan189.github.io/react-naver-maps)를 참고하세요.

## 개발

### 의존성 설치

```bash
npm install
```

### 개발 모드 실행

```bash
npm run dev
```

### 빌드

```bash
npm run build
```

### 타입 체크

```bash
npm run type-check
```

### 린트

```bash
npm run lint
```

## 문서

상세한 사용법, API 문서, 예제는 [문서 사이트](https://knsan189.github.io/react-naver-maps)에서 확인할 수 있습니다.

## 기여

버그 제보와 기능 제안은 [GitHub Issues](https://github.com/knsan189/react-naver-maps/issues)에 남겨 주세요. 코드 기여는 저장소를 포크한 뒤 Pull Request로 보내 주세요.

## 주요 기능

- 🗺️ 네이버 지도 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