fix: react-maplibre - support maplibre-gl v6

[miketu926]

Fixes #2597.

Summary

Adds MapLibre GL JS v6 support to the react-maplibre wrapper while preserving compatibility with v4 and v5. MapLibre v6 removed the public map.transform property and replaced direct transformCameraUpdate assignment with setTransformCameraUpdate().

Changes

• Reconstructs the controlled-camera transform snapshot from public camera getters instead of reading map.transform.
• Uses canvas dimensions for resize checks.
• Detects setTransformCameraUpdate() at runtime and falls back to the legacy transformCameraUpdate property on v4/v5.
• Defaults center elevation to zero when getCenterElevation() is unavailable on pre-v5 MapLibre.
• Bridges event and layer-property type differences across MapLibre v4/v5/v6 without changing the public React API.
• Configures the MapLibre v6 worker URL in the Vite browser-test harness.
• Tests the wrapper against MapLibre ^4.0.0, ^5.0.0, and ^6.0.0 in CI.

Testing

• Added focused tests for every public camera getter, the pre-v5 elevation fallback, padding identity, and LngLat identity.
• Verified that controlled-camera synchronization does not access map.transform.
• Full lint, TypeScript build, Node tests, browser coverage tests, and all three MapLibre CI matrix lanes pass.

---

Note

Medium Risk
Changes core map camera sync and event wiring used on every map instance; mistakes could affect view state or handlers across v4–v6, though feature detection limits blast radius.

Overview
Adds maplibre-gl v6 support in the react-maplibre wrapper while keeping v4/v5 working. Dev dependency and CI matrix now include ^6.0.0; browser tests set the v6 worker URL when needed for Vite.

Camera / view state: v6 drops public map.transform and assigning transformCameraUpdate. The wrapper uses getTransformLike() (public getters) for view-state sync and resize checks (canvas.clientWidth/Height), and registers camera updates via setTransformCameraUpdate() when present, otherwise the legacy property.

Types / events: MapBoxZoomEvent is derived from MapEventType after the v6 rename; map.on() handlers are typed with keyof MapEventType. Layer updates use as any on layout/paint property keys to satisfy v6’s stricter setLayoutProperty / setPaintProperty types.

Tests cover getTransformLike (including pre-v5 elevation default).

^{Reviewed by Cursor Bugbot for commit 732bbef. Bugbot is set up for automated code reviews on this repo. Configure here.}

[miketu926]

• Xiaoji Chen
• Xintong Xia

[tordans]

Does the package have a setup to test each version separately?

[miketu926]

Does the package have a setup to test each version separately?

No.. CI only tests against whatever version is pinned in package.json (bumped to ^6.0.0 here). The v4/v5 fallback path is manually verified via type-checks, not an automated test.. that's been the case for this repo generally, not specific to this PR. Could open a follow-up for a version matrix if that's wanted.

[tordans]

CI only tests against whatever version is pinned in package.json (bumped to ^6.0.0 here). The v4/v5 fallback path is manually verified via type-checks, not an automated test.. that's been the case for this repo generally, not specific to this PR.

Thanks

Could open a follow-up for a version matrix if that's wanted.

Personally I think this would be a good addition given that we start working around version specifics. But maybe lets wait for a signal from the maintainers.

[chrisgervang]

Personally I think this would be a good addition given that we start working around version specifics. But maybe lets wait for a signal from the maintainers.

I could be open to it, though I'd like input from @Pessimistress since she's thought a lot about version compatibility. And as @miketu926 mentioned - the type system is catching the majority of version compatibility issues.

Overtime, we have had to drop support for older major versions when they diverge greatly - then we must document the last react-map-gl version with support for X basemap version.

[chrisgervang]

I traced the current CI failure and opened #2599 to move the repository CI/development runtime to Node.js 24.18.0. Once #2599 is merged, please rebase this PR onto master.

That removes the jsonlint Node engine blocker, but two PR-local failures remain afterward:

1. The MapLibre 6 dependency graph installs gl-matrix 3.4.4 alongside the existing 3.4.3, causing duplicate TypeScript declarations. Deduplicate gl-matrix at 3.4.4 and commit the resulting yarn.lock update. A root Yarn resolution to 3.4.4 is one validated approach.
2. Run Prettier on modules/react-maplibre/src/maplibre/maplibre.ts.

I validated that Node 24 plus the gl-matrix 3.4.4 resolution builds successfully; yarn lint then reports only that formatting issue from this PR.

[Pessimistress]

I suspect we may get more divergence as v6 development continues, and will eventually need a dedicated endpoint. But for now the changes seem manageable.

[miketu926]

@Pessimistress updated MCs against latest

[chrisgervang]

Added CI test matrix

[chrisgervang]

Had to get a little create to bridge types that aren't available on older versions.

Edit: We discussed it we'll relax the type safety to key as any since they are internal APIs, which is our typical pattern for cross-version compatibility. The alternative is to add a /maplibre6 but given its not user-facing, I don't think its necessary

[vinuganesan]

@miketu926 I'm getting following error when I use with my next.js@16 project.

Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/html". Strict MIME type checking is enforced for module scripts per HTML spec. http://localhost:3000/_next/static/media/maplibre-gl-shared.mjs

[miketu926]

Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/html". Strict MIME type checking is enforced for module scripts per HTML spec. http://localhost:3000/_next/static/media/maplibre-gl-shared.mjs

Issue is unrelated to maplibre support. You'll need a /public route for that .mjs file

[chrisgervang]

Yes, I ran into similar issues upgrading our website and examples. From a user's pov, this feels like a regression and I hope they can improve it in the future..

We've added a note in our get started guide and the release notes about v6's new bundler setup requirements.

Their installation snippets were helpful.

Docusaurus, Webpack, and Vite users can see #2602 for how we upgraded this package.