2026년 8월 17일

React SDK 0.2.0 ── 21개 패키지, 개명, 그리고 번들러 밖에서 읽히지 않는 것

21개 패키지를 동일 버전으로 공개했습니다. react-geojson-layer의 개명, 내용이 비어 있던 react-for-mapkit의 수정, 그리고 번들러 밖에서 무엇이 읽히고 무엇이 읽히지 않는지를 정리하고 있습니다.

MapConductor React SDK가 0.2.0 이 되었습니다. npm 상의 21개 패키지, 모두 Apache-2.0입니다. @mapconductor/react-for-openlayers 만 0.2.1이고, 이유는 마지막에 씁니다.

바뀐 것

전 패키지의 버전을 맞췄습니다. 내부의 @mapconductor/* 의존 범위도 동시에 움직여 두었으므로, 의도하지 않은 버전 혼재는 일어나지 않습니다.
@mapconductor/react-geojson-layer 를 @mapconductor/react-geojson 으로 개명했습니다. 바뀐 것은 패키지 이름뿐이고, GeoJSONLayer, GeoJSONLayerState, GeoJSONParser 같은 API는 그대로입니다. 구 패키지는 0.1.3인 채로 npm에 남지만, 앞으로의 갱신은 없습니다.
4개의 패키지를 처음으로 공개했습니다. react-for-arcgis, react-for-mappls, react-geojson, react-kml 입니다.
react-for-mapkit 에 내용이 들어갔습니다. 0.1.3은 LICENSE와 README밖에 포함하고 있지 않았습니다. 빌드 대상의 일람에서 빠져 있어, files: ["dist"] 가 아무것에도 매치하지 않았기 때문입니다. 0.1.3을 쓰고 계신 경우는 올려 주세요.
라이선스 식별자를 Apache-2.0 으로 고쳤습니다. 그때까지 Apache2 라는 SPDX로서 부정한 값이었고, 도구에서는 「식별할 수 없는 라이선스」로 다뤄지고 있었습니다.

지도 SDK의 의존은, 선언된 범위 내의 최신으로 갱신했습니다. 실제로 움직인 것은 maplibre-gl(6.3.0 → 6.4.0)과 @turf/turf(7.3.5 → 7.4.0)의 2개뿐이고, 나머지는 이미 최신이었습니다.

패키지와, 각각이 쓰는 지도 SDK

패키지	버전	지도 SDK	저장소
`@mapconductor/js-sdk-core`	0.2.0	—	js-sdk-core
`@mapconductor/js-sdk-react`	0.2.0	—	js-sdk-react
`@mapconductor/react-for-arcgis`	0.2.0	`@arcgis/core` ^5.1.16	react-for-arcgis
`@mapconductor/react-for-azuremaps`	0.2.0	`azure-maps-control` ^3.7.0	react-for-azuremaps
`@mapconductor/react-for-cesium`	0.2.0	`cesium` ^1.131.0	react-for-cesium
`@mapconductor/react-for-googlemaps`	0.2.0	`@googlemaps/js-api-loader` ^2.1.1	react-for-googlemaps
`@mapconductor/react-for-here`	0.2.0	CDN (global `H`)	react-for-here
`@mapconductor/react-for-leaflet`	0.2.0	`leaflet` ^1.9.4	react-for-leaflet
`@mapconductor/react-for-longdo`	0.2.0	CDN (`api.longdo.com/map3`)	react-for-longdo
`@mapconductor/react-for-mapbox`	0.2.0	`mapbox-gl` ^3.15.0	react-for-mapbox
`@mapconductor/react-for-mapkit`	0.2.0	CDN (`cdn.apple-mapkit.com`)	react-for-mapkit
`@mapconductor/react-for-maplibre`	0.2.0	`maplibre-gl` ^6.0.0	react-for-maplibre
`@mapconductor/react-for-mappls`	0.2.0	`mappls-web-maps` ^3.8.1	react-for-mappls
`@mapconductor/react-for-maptiler`	0.2.0	`maplibre-gl` ^6.0.0	react-for-maptiler
`@mapconductor/react-for-openlayers`	0.2.1	`ol` ^10.2.1	react-for-openlayers
`@mapconductor/react-for-tomtom`	0.2.0	`@tomtom-org/maps-sdk` ^0.51.0, `maplibre-gl` ^5.24.0	react-for-tomtom
`@mapconductor/react-geojson`	0.2.0	—	react-geojson
`@mapconductor/react-heatmap`	0.2.0	—	react-heatmap
`@mapconductor/react-icons`	0.2.0	—	react-icons
`@mapconductor/react-kml`	0.2.0	—	react-kml
`@mapconductor/react-marker-clustering`	0.2.0	—	react-marker-clustering

3개의 프로바이더는 의존에 지도 SDK를 가지지 않습니다. SDK가 npm으로 배포되고 있지 않기 때문입니다. HERE, Apple MapKit JS, Longdo 는 실행 시에 벤더의 CDN에서 읽히므로, 실제로 동작하는 버전은 벤더가 배포하고 있는 것이 됩니다.

react-for-tomtom 만 maplibre-gl 을 5.x인 채로 두었습니다. @tomtom-org/maps-sdk 가 maplibre-gl@^5.24.0 에 의존하고 있기 때문이며, 6.x로 올리면 MapLibre가 2개 들어가, TomTom SDK가 상정하고 있지 않은 map 객체를 넘기게 됩니다.

ESM・CommonJS・SSR

이들 패키지는 번들러를 전제로 하고 있습니다. Vite・webpack・Next.js・Metro에서는 올바르게 해결되며, 전 프로바이더에 대해 릴리스 전에 실제 브라우저에서의 렌더링을 확인하고 있습니다.

한편, Node 자신의 해결기 에 직접 읽히는 경우 ── 순수한 node, 번들러를 통하지 않는 SSR 엔트리, Vitest의 node 환경 등 ── 은 이야기가 다릅니다. 기반이 되는 지도 SDK가 브라우저용 라이브러리이기 때문입니다. 공개된 패키지를 빈 프로젝트에서 실제로 import 해서 계측한 결과입니다.

패키지	`import`	`require()`	이유
`react-for-arcgis`	no	no	`@arcgis/core/views/MapView` imports `.css`, which Node cannot load. Any map needs `MapView`, so this cannot be worked around from our side.
`react-for-leaflet`	no	no	`leaflet` touches `window` while the module is evaluated.
`react-for-azuremaps`	no	no	`azure-maps-control` touches `window` while the module is evaluated.
`react-for-tomtom`	no	no	Reads `maplibre-gl/package.json`, which Node will only load with an import attribute.
`react-for-mappls`	no	yes	`mappls-web-maps` is CommonJS, so its named exports cannot be statically analysed by the ESM loader.
`react-for-maplibre`	yes	no	`maplibre-gl` v6 is ESM-only and declares no CommonJS entry.
`react-for-maptiler`	yes	no	Same as `react-for-maplibre`.

나머지 14개 패키지는 양쪽에서 읽어 들일 수 있습니다. 이 결과는 0.1.3에서도 동일 하므로, 0.2.0에서 새로 일어난 것이 아닙니다.

짚어 두면 좋은 점이 2가지 있습니다.

SSR에서는, 프로바이더를 클라이언트 쪽에서 지연 import 해 주세요. 브라우저 전용 프로바이더를 톱 레벨에서 정적 import 하면, 번들러를 통하지 않는 서버 렌더링은 망가집니다. 공식 web 샘플은 lazy(() => import('./providers/...')) 를 쓰고 있고, 그 때문에 Vite의 SSR 빌드가 통과하고 있습니다.
react-for-maplibre・react-for-maptiler・react-for-tomtom 은, 실제로는 동작하지 않는 CommonJS 엔트리를 선언하고 있습니다. maplibre-gl v6이 CommonJS를 그만두었기 때문입니다. 이 3개는 ESM으로 써 주세요. exports 에서 require 를 떼는 것은 앞으로의 릴리스에서 대응합니다.

유일하게 이쪽이 원인이었던 것

react-for-openlayers 가 Node ESM에서 읽히지 않았던 것은, OpenLayers와는 관계없는 이유였습니다. 우리 자신의 소스가 ol/proj 를 확장자 없이 import 하고 있었고, Node는 이것을 디렉터리 import로 거부합니다. 번들러는 통과시켜 버리기 때문에 알아차리지 못했습니다. 0.2.1 에서 수정 완료입니다. 변경은 이 한 줄뿐이고, 번들러 경유의 거동은 달라지지 않습니다.

설치

bash

npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react @mapconductor/react-for-maplibre

각 패키지는 각각 독립된 저장소에 있습니다. github.com/MapConductor 를 봐 주세요.