Angular 프로젝트에서 mapbox-gl npm 패키지와 TypeScript를 통합해 기본 지도 렌더링 구현

Context

Angular 프로젝트에 지도와 상호작용 기능을 추가하는 작업은 초기에는 복잡할 수 있다. Mapbox는 여러 통합 방식을 제공하는데 가장 직관적인 방식을 명확히 구분할 필요가 있다.

Technical Solution

• mapbox-gl npm 패키지 설치: npm i --save mapbox-gl로 라이브러리 의존성 추가
• CDN을 통한 스타일시트 로드: index.html의 head 태그에 Mapbox GL CSS v3.13.0 링크 포함
• 공개 액세스 토큰 설정: Mapbox 계정에서 생성한 공개 토큰(pk.)을 컴포넌트의 accessToken 속성에 할당
• AfterViewInit 생명주기 훅 활용: 뷰 초기화 후 mapboxgl.Map 인스턴스를 생성하고 container, style, center, zoom 옵션 구성
• CSS 레이아웃 보정: map 컨테이너의 width/height를 100%로 설정하고 부모 요소에는 100vw/100vh 적용, 전역 margin/padding 초기화

Key Takeaway

Mapbox를 Angular에 통합할 때는 CDN 스타일시트 로드와 생명주기 훅의 올바른 타이밍이 필수이다. 지도 렌더링 실패 대부분은 컨테이너의 명시적 크기 정의 누락이나 전역 스타일 상속으로 발생하므로 레이아웃 구조를 먼저 점검해야 한다.