Add @deck.gl/maplibre for MapLibre GL JS v4/5/6 - #10566

Greptile Summary

The PR introduces a dedicated MapLibre integration package supporting overlaid and interleaved rendering across MapLibre GL JS versions 4.5.1 through 6.

• Adds MapLibreOverlay, compatibility helpers, layer-group synchronization, tests, and package exports.
• Migrates MapLibre examples, documentation, the main bundle, and the Jupyter widget to the new package.
• Updates MapLibre and React integration dependencies and worker configuration.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

sequenceDiagram
  participant App
  participant MapLibreOverlay
  participant MapLibre
  participant Deck
  App->>MapLibre: Create map
  App->>MapLibreOverlay: Construct with layers and mode
  App->>MapLibre: addControl(overlay)
  MapLibre->>MapLibreOverlay: onAdd(map)
  alt Interleaved
    MapLibreOverlay->>Deck: Create with shared WebGL2 context
    MapLibreOverlay->>MapLibre: Add custom layer groups
    MapLibre->>MapLibreOverlay: Render layer groups
    MapLibreOverlay->>Deck: Draw matching deck.gl layers
  else Overlaid
    MapLibreOverlay->>Deck: Create separate canvas
    MapLibre->>MapLibreOverlay: Camera movement events
    MapLibreOverlay->>Deck: Synchronize view state
  end

_{Reviews (13): Last reviewed commit: "use maplibre 6 in examples" | Re-trigger Greptile}

Thanks @birkskyum! Left a review - overall supportive of the split, a long time coming. Agree that the modules are diverging. My main feedback is to revert dropping react-map-gl, and instead upgrade to 8.1 which ships support for v6.

Thanks! The React example is back on react-map-gl, upgraded to v8.1 with MapLibre v6 support.

The biggest risk with this change is making is clear which versions and modules to use - maplibre <6 still uses the mapbox module. If it's possible, I'd prefer we follow up with a compatibility layer for older maplibre versions in the maplibre module. Then, in the next major version of deck we can drop support for maplibre entirely from the mapbox module with the goal being to simplify and focus the modules, where possible.

I added a small isolated compatibility layer for MapLibre GL JS 4.5.1 and v5, while keeping v6 as the primary path. Version 4.5.1 is the minimum because it is the first v4 release to expose the custom-layer render parameters needed for doing interleaved rendering only relying on maplibre's public API.

So, @deck.gl/maplibre now supports 4.5.1, v5, and v6, and we can guide supported MapLibre users to this package in deck.gl 9 and remove MapLibre compatibility from @deck.gl/mapbox in the next major version.

coverage: 82.18% (-0.3%) from 82.497% — birkskyum:dedicated-maplibre6-package into visgl:master

fyi #10551 may need to be applied to this module

fyi #10551 may need to be applied to this module

@chrisgervang We shoudl be good already. This case is covered in the getMapLibreProjection() in compatibility.ts

Want your agent to iterate on Greptile's feedback? Try greploops.

Is this good to go @birkskyum?

@chrisgervang yes, it's ready now.

Thanks for processing this! I think it's a big step forward to now be fully on public api, and relying on the maplibre type definitions. Would it be possible to cut a 9.4.0-alpha.3 release to get @deck.gl/maplibre on npm?

Yes, we'll be cutting one soon

@chrisgervang
Hello, I don't seem to see the 9.4.0+alpha.3 version.

@tangs8dj , it's released in @deck.gl/maplibre and deck.gl v9.4.0-beta.1