I created a plugin that simplifies the integration of Google Maps into Vite and React

Context

Vite와 React를 사용하는 프로젝트에서 Google Maps JavaScript API를 통합할 때 APIProvider로 앱을 래핑하고, 지도 설정(zoom, center, controls)을 반복적으로 구성해야 하는 보일러플레이트 코드가 발생한다. 여러 지도를 사용하는 앱에서 각각 다른 설정을 관리할 때 설정 중복이 증가한다.

Technical Solution

• APIProvider 자동 래핑: 플러그인이 앱 최상단에서 APIProvider를 자동으로 적용하여 수동 래핑 제거
• 가상 모듈 @google-maps/map 제공: 사전 구성된 Map 컴포넌트를 가상 모듈로 제공하여 직접 import 가능하도록 구현
• 전역 기본값 설정: vite.config.ts의 mapDefaults 객체에서 defaultZoom, defaultCenter, gestureHandling, fullscreenControl 등을 한 번에 정의
• Google Maps 라이브러리 번들링: places, marker 등 필요한 Google Maps 라이브러리를 libraries 배열로 선언하여 자동 로드
• 속성 오버라이드 메커니즘: 각 Map 컴포넌트의 props로 전역 기본값을 지역 수준에서 재정의 가능하도록 설계
• 디버그 패널 제공: debug: true 옵션 활성화 시 지도 로드 상태, zoom 레벨, 커서 위치, 클릭 좌표를 개발 패널에서 표시
• TypeScript 모듈 선언: types.d.ts에서 @google-maps/map 모듈을 declare하여 @vis.gl/react-google-maps의 타입 지원

Key Takeaway

플러그인 기반 자동화 설정은 개별 프로젝트의 반복 작업을 제거하고, 전역 기본값과 지역 오버라이드 패턴을 결합하면 다양한 구성 요구사항을 단일 설정점에서 관리할 수 있다.