RFC: react-map-gl v7.0

[Pessimistress]

Background

react-map-gl was originally created by Uber's visualization team to work with deck.gl. Aside from providing a React-friendly wrapper for Mapbox GL JS, it currently also addresses use cases including:

• Provide a base map layer for other visualization overlays, most extensively used in deck.gl and kepler.gl.
• A source of React map components without mapbox-gl dependency, including Marker, Popup and NavigationControl

The project was transferred to the Urban Computing Foundation in April 2020.

Issues with the current code base

Diverged dependencies

react-map-gl currently have two releases in production:

• v5.3 supports mapbox-gl v1 and maplibre-gl
• v6.1 supports mapbox-gl v2

The divergence happened when Mapbox changed its license, see #1380. It has become increasingly difficult to maintain as Maplibre and Mapbox start making more aggressive breaking changes.

Override of the native event handling

react-map-gl disables mapbox-gl's native event handling and implements its own. This is arguably the one most controversial design decision of this project, dated back to before the current maintainers were involved. Lengthy discussions have been had (e.g. #569, mapbox/mapbox-gl-js#3746, #725) and continues to generate hard-to-resolve feature requests (#574, #1640, #1353, #775) and performance issues (#1151, #909).

Despite major efforts to improve the usability of the custom controller, it still has many open issues. The code base is quite complex already, with few developers able to navigate and contribute. Considering the complexity of the task, it is unlikely for the current release to support Mapbox's non-WebMercator projection feature in its current state.

Proposal

This RFC is gathering feedback for the following major breaking changes proposed for react-map-gl v7.

• Make mapbox-gl a peer dependency so that the library is impartial about the version/fork used.
• Drop the usage of mjolnir.js' EventManager and subsequently MapController altogether. Instead, we will pursue exposing mapbox-gl's native event system and attempt to hijack the camera change under the hood.
• This will allow users to use the latest rendering and interactive options when they are released by Mapbox.
• 3rd-party Mapbox addons will be supported by default.
• We can add a stateful version of MapGL that renders fully asynchronously without any performance impact.
• Remove transition interpolator classes and use native methods such as Map.flyTo and Map.easeTo.
• Custom MapController classes will stop working.
• Remove the overlay classes.
• Components such as Marker, Popup etc. will no longer be mapbox-independent. We will use React portal to render them into mapbox-gl's control container, instead of floating outside of the map container. deck.gl applications that render these components as children of DeckGL will stop working. I propose we move some of the current code to a new React component library that is independent from mapbox-gl.
• Rewrite the code base in TypeScript.

The goal is to have a code base that is less demanding to maintain, and more focused on the most common use cases. To achieve this, we have to drop some niche use cases and/or move their support to other projects.

[Pessimistress]

cc @heshan0131 @supersonicclay @chrisgervang

[ibgreen]

This sounds like the right move to secure the future of this framework. This should make the code base considerably simpler, and both reduce the burden on current maintainer and make the react-map-gl code more accessible to new maintainers as well as the community.

Is it possible to quickly spin up a prototype? Being able to see an alpha release of the new approach work in a major app like kepler.gl would be a big confidence builder.

I propose we move some of the current code to a new React component library that is independent from mapbox-gl.

nebula.gl also has some at least superficially similar overlay components. Perhaps an alignment opportunity?

[Pessimistress]

I have pushed a proof of concept here: https://github.com/visgl/react-map-gl/tree/prototype

Tested with the following use cases:

• Controlled component

function App() {
  const [viewState, setViewState] = useState({
    latitude: 40,
    longitude: -100,
    zoom: 3.5,
    bearing: 0,
    pitch: 0
  });

  return <Map
    {...viewState}
    onMove={({viewState}) => setViewState(viewState)}
    mapStyle="mapbox://styles/mapbox/dark-v9"
  />;
}

• Stateful component

function App() {
  return <Map
    initOptions={{
      latitude: 40,
      longitude: -100,
      zoom: 3.5,
      bearing: 0,
      pitch: 0
    }}
    mapStyle="mapbox://styles/mapbox/dark-v9"
  />;
}

• External controller

function App() {
  return <DeckGL
    initialViewState={{
      latitude: 40,
      longitude: -100,
      zoom: 3.5,
      bearing: 0,
      pitch: 0
    }}
    controller
  >
    <Map mapStyle="mapbox://styles/mapbox/dark-v9" />
  </DeckGL>;
}

[alasarr]

Thanks a lot for the huge work here @Pessimistress.

It totally makes sense to me, vis.gl should continue being basemap agnostic. It reduces complexity, it's easy for maintainers, and brings the possibility of getting the features implemented by the new providers.

Definitely, a better strategy for the current situation with mapbox-gl.

@VictorVelarde we should try this prototype after the Christmas holidays to see how it fits in CARTO products (mainly CARTO for React and Builder)

cc: @zbigg @padawannn @bbecquet @felixpalmer @Josmorsot

[Pessimistress]

You can try the work-in-progress release with react-map-gl@beta.

Docs: https://github.com/visgl/react-map-gl/tree/7.0-dev/docs/api-reference

[timsluis]

Thanks a lot @Pessimistress. Tried it yesterday and it is already working like a charm! It's faster, it is (way) smaller and less lines of codes are needed for implementing it in our own codebase. 👏

[felixpalmer]

Great to see this. Thanks for all the effort @Pessimistress.

I have two questions regarding the reversal of control flow (dropping mjolnir):

• As this will mean that the Mapbox map "controls" deck.gl, we will be moving closer to what we currently do with the Google maps overlay. Is it feasible that in the future react-map-gl could be adapted to use the Google basemap also?
• As the EventManager is removed, will this mean that nebula.gl will not work with this component anymore? https://github.com/uber/nebula.gl/blob/3f21c8754dbadbfaa7282cf053ecc894733ca15a/modules/layers/src/layers/editable-layer.ts#L81

[Pessimistress]

@felixpalmer You can still use DeckGL to control the map, which is the main use case for nebula and all deck.gl examples. It's just that react-map-gl no longer implements a controller.

[timsluis]

Hi @Pessimistress, I have been testing v7 quite extensively. How do you want to receive the feedback?

[Pessimistress]

@timsluis That's what this thread is for.

[timsluis]

Three things I noticed:

• The customAttributions prop of the AttributionControl component should be called customAttribution.
• If you have React Strict Mode turned on, the Popup component will create two popup objects and adds them both to the map. Only one will be removed once when you unmount the Popup component. This happens because Strict Mode intentionally double-invokes the State updater functions (the first argument to setState). This is where the popup gets created and added to the map object.
• Also, the content of a popup is rendered into the React Portal after the Popup has been added to the Mapbox map. This causes the popup to be placed partly outside the viewport (if opened on the edge of the screen), since Mapbox isn't able to position it correctly. After a map interaction the Popup is positioned correctly again.