maplibre-gl v6 blocked: plugin ecosystem still ships v5-era builds

[giswqs]

maplibre-gl v6 cannot land until the plugin ecosystem ships v6-compatible builds. Tracking what has to happen first, so the next Dependabot bump (#1482) is not re-attempted blind.

Why it is blocked

MapLibre v6 is an ESM-only distribution with no default export and no CJS build (the UMD and maplibre-gl-csp bundles are gone). See the v5 → v6 migration guide.

Three separate breakages result, and only the third is ours to fix:

1. Third-party packages ship dist compiled against v5's default export

import maplibregl from "maplibre-gl" is a hard bundling error against v6 ("default" is not exported by maplibre-gl.mjs). These 11 installed packages still do it in their published dist/:

opengeos-owned (9) — need a namespace-import migration + rebuild + release:

• maplibre-gl-3d-tiles
• maplibre-gl-components
• maplibre-gl-duckdb
• maplibre-gl-geo-editor
• maplibre-gl-geoagent
• maplibre-gl-overture-maps
• maplibre-gl-raster
• maplibre-gl-streetview
• maplibre-gl-swipe

external (2) — we can only wait or shim:

• @esri/maplibre-arcgis
• @geoman-io/maplibre-geoman-free

Note maplibre-gl-raster uses the mixed form import maplibregl, { Popup } from "maplibre-gl", so a scan that only looks for the bare default import will miss it.

Re-check with:

grep -rlE 'import +[A-Za-z_$][A-Za-z0-9_$]* *(,[^;]*)? *from *["'"'"']maplibre-gl["'"'"']|require\( *["'"'"']maplibre-gl["'"'"'] *\)' \
  --include='*.js' --include='*.mjs' --include='*.cjs' \
  node_modules/maplibre-gl-* node_modules/@esri/maplibre-arcgis node_modules/@geoman-io/*

2. v6 dropped CJS, which breaks the Node test suite

Those packages are dual-published, and their .cjs entries require("maplibre-gl"). v6's exports map has only types and import conditions, so CJS resolution fails outright:

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in node_modules/maplibre-gl/package.json

npm run test:frontend fails 29 tests on this. A Vite-level shim cannot help — node --test does not go through Vite.

3. GeoLibre patches the MapLibre namespace (ours to fix)

packages/map/src/globe-popup-occlusion.ts installs globe-occlusion behavior by assigning over the namespace:

api.Popup = GeoLibrePopup;   // map-controller.ts calls installGlobePopupOcclusion(maplibregl)

Under v5's mutable CJS/UMD default export this worked. A v6 ESM namespace object is getter-only, so it throws at boot:

TypeError: Cannot set property Popup of #<Object> which has only a getter

The app never mounts the map canvas — 22 of 23 e2e tests fail. This needs a different mechanism (the patch exists so third-party plugins constructing new maplibregl.Popup() also get occlusion, so simply exporting a GeoLibrePopup for our own call sites is a behavior change worth deciding on deliberately).

What is already done

A local wip branch carries the GeoLibre-side migration, verified with tsc -b clean, eslint 0 errors, and a successful vite build:

• Dedupe to a single copy. The Dependabot lockfile resolved both 5.24.0 (hoisted, to satisfy @maplibre/maplibre-gl-directions' ^5.0.0 peer — there is no v6-compatible release of it) and 6.0.0 (nested in the three workspaces that declare it), so Map was a different nominal type across package boundaries. That is what the original CI errors (Argument of type 'SwipeControl' is not assignable to parameter of type 'IControl') actually were — not an API change. Fixed with a root overrides entry.
• 33 files migrated to import * as maplibregl from "maplibre-gl".
• v6's tightened typing: set/getPaintProperty and set/getLayoutProperty are now generic over keyof AllPaintProperties / keyof AllLayoutProperties, and Map#on/off's catch-all overload narrowed from type: string to type: keyof MapEventType (which breaks binding third-party events such as Geoman's gm:*). Added packages/map/src/dynamic-style-property.ts so the unavoidable casts for runtime-computed property names live in one documented place.

Suggested order

1. Migrate + release the 9 opengeos packages (namespace imports, rebuild, verify the .cjs entry no longer requires maplibre-gl).
2. Rework globe-popup-occlusion.ts off namespace patching.
3. Wait on / track @esri/maplibre-arcgis and @geoman-io/maplibre-geoman-free. @maplibre/maplibre-gl-directions also still pins maplibre-gl@^5.0.0 as a peer.
4. Re-run the bump and re-check the frontend + e2e suites, not just the build — the build passes with a shim while the app is completely broken at runtime, so a green build alone proves nothing here.

Until then, maplibre-gl should stay on 5.x and Dependabot bumps to v6 should be closed with a pointer to this issue.

[giswqs]

Update: blocker 1 is cleared for all opengeos packages

All nine opengeos maplibre-gl-* packages are now released with the default import removed, and each published tarball has been verified against the registry (not just a local build):

Package	Version	PR
maplibre-gl-swipe	0.11.1	opengeos/maplibre-gl-swipe#21
maplibre-gl-3d-tiles	0.5.6	opengeos/maplibre-gl-3d-tiles#21
maplibre-gl-duckdb	0.2.4	opengeos/maplibre-gl-duckdb#11
maplibre-gl-raster	0.14.4	opengeos/maplibre-gl-raster#63
maplibre-gl-overture-maps	0.3.2	opengeos/maplibre-gl-overture-maps#10
maplibre-gl-geoagent	0.5.6	opengeos/maplibre-gl-geoagent#32
maplibre-gl-geo-editor	0.10.2	opengeos/maplibre-gl-geo-editor#39
maplibre-gl-components	0.30.0	opengeos/maplibre-gl-components#129
maplibre-gl-streetview	0.7.0	(no change needed)

All are non-breaking: v5 already exports these as named exports (its default only ever existed through CJS interop), so they resolve on both v5 and v6. No peer range narrowed.

maplibre-gl-streetview needed nothing — its src/ was already clean. Its only hit was in the .cjs build, where require("maplibre-gl") is simply how CJS references an externalized dependency (see blocker 2, which no source change can fix).

Two things worth recording

maplibre-gl-components needed a packaging change, not just imports. It was inlining @geoman-io/maplibre-geoman-free (which reaches it only via maplibre-gl-geo-editor, where it is already a peer), baking Geoman's own maplibre-gl default import into its dist/ — unfixable from that package's source. Geoman is now external and a declared peer (>=0.5.0), mirroring the rationale already documented there for the LiDAR controls. Released as a minor bump for the new peer requirement.

The lockfile, not the version range, decided what got bundled. components' publish workflow runs npm ci, and its lockfile still pinned swipe 0.7.1 / geo-editor 0.7.3 — both carrying the default import. Left alone, CI would have gone green and published a dist that was still v6-broken. The lockfile was bumped to the fixed releases before cutting v0.30.0. Worth remembering for any package here that inlines its siblings.

Still blocking v6

Blocker 1 (partial) — the two external packages still ship the default import in their ESM builds, so GeoLibre continues to need a shim for them:

• @esri/maplibre-arcgis
• @geoman-io/maplibre-geoman-free

Blocker 2 — unchanged. v6 has no CJS build, so any .cjs entry that references maplibre-gl cannot resolve. This is what fails 29 frontend tests under node --test; it needs a GeoLibre-side fix (resolve these packages as ESM in the test runner), not an upstream one.

Blocker 3 — unchanged. packages/map/src/globe-popup-occlusion.ts still assigns maplibregl.Popup, which v6's getter-only namespace forbids, so the app does not boot.

[giswqs]

Update: GeoLibre now consumes the blocker-1 releases

#1506 bumps the ranges so the fixed builds are what actually installs. Previously the caret ranges were still pinned to the pre-fix versions, so the releases listed above were published but not yet resolved by this repo.

Package	From	To
maplibre-gl-3d-tiles	0.5.5	0.5.6
maplibre-gl-components	0.29.0	0.30.0
maplibre-gl-duckdb	0.2.3	0.2.4
maplibre-gl-geo-editor	0.10.1	0.10.2
maplibre-gl-geoagent	0.5.5	0.5.6
maplibre-gl-overture-maps	0.3.1	0.3.2
maplibre-gl-raster	0.14.3	0.14.4
maplibre-gl-swipe	0.11.0	0.11.1

maplibre-gl-streetview was already at 0.7.0. The PR also carries unrelated whitebox-wasm 0.5.1 / geolibre-wasm 1.4.0 bumps.

This does not move maplibre-gl off 5.x — it only removes the reason the next attempt would have failed on blocker 1.

Re-running the scan against the new tree

The scan from the issue body now returns only .cjs files for the opengeos packages:

node_modules/maplibre-gl-3d-tiles/dist/ThreeDTilesControl-*.cjs
node_modules/maplibre-gl-components/dist/index.cjs
node_modules/maplibre-gl-components/dist/ControlGrid-*.cjs
node_modules/maplibre-gl-duckdb/dist/DuckDBControl-*.cjs
node_modules/maplibre-gl-geo-editor/dist/geo-editor-*.cjs
node_modules/maplibre-gl-geoagent/dist/GeoAgentControl-*.cjs
node_modules/maplibre-gl-overture-maps/dist/OvertureMapsControl-*.cjs
node_modules/maplibre-gl-streetview/dist/StreetViewControl-*.cjs
node_modules/maplibre-gl-swipe/dist/SwipeControl-*.cjs

Not a regression — that is blocker 2 wearing blocker 1's clothes. Those hits are require("maplibre-gl") in the CJS entry, which is just how CJS references an externalized dep and is exactly what the streetview note above described. Zero ESM hits remain from opengeos packages, which is the part that matters for the Vite build.

The two external packages are unchanged and still hit in ESM, so the shim is still required:

• @esri/maplibre-arcgis 1.3.0 (latest) — dist/esm/maplibre-arcgis.js
• @geoman-io/maplibre-geoman-free 0.8.4 (latest) — dist/maplibre-geoman.es.js

Worth noting their peer ranges are open-ended (>=5.11.0 and >=5.19.0), so npm will happily install them alongside v6 — nothing warns, and the failure surfaces only as a bundling error. @maplibre/maplibre-gl-directions 0.9.1 (latest) still pins maplibre-gl@^5.0.0, so the root overrides dedupe entry described above is still needed to avoid the two-copies-of-Map nominal type problem.

Verification

Full suite green on the bumped tree, with maplibre-gl still on 5.x: test:frontend 4227 passed / 0 failed, tsc -b && vite build clean, test:e2e 23/23. The e2e run was not a formality here — maplibre-gl-components 0.30.0 externalizes Geoman rather than inlining it, which is a real runtime packaging change.

Remaining blockers

• Blocker 1 (external only) — @esri/maplibre-arcgis and @geoman-io/maplibre-geoman-free, both already at latest. Nothing to do but track upstream or shim.
• Blocker 2 — unchanged. Still needs a GeoLibre-side fix to resolve these packages as ESM under node --test.
• Blocker 3 — unchanged. packages/map/src/globe-popup-occlusion.ts still assigns maplibregl.Popup.

Blocker 3 is the one that still needs a design decision, not just mechanical work, since the patch exists so third-party plugins constructing new maplibregl.Popup() inherit occlusion.