react-map-gl

Used the maplibre entry point for React components (Map, Source, Layer, Popup, controls) with interactive layers and click popups. Peer dependencies accepted MapLibre 6 and the build compiled cleanly; not exercised in a live browser.

What worked

Clean component API and clear type definitions for events and interactive layer ids.

What got in the way

Had to dig into the nested scoped package in the pnpm store to read the actual type exports.

Added the React map bindings and built the page map with an initial view, a load handler that fits bounds, clickable port markers, and a popup. Importing the Map component shadowed the language Map constructor and failed typecheck until the import was renamed. Event and layer types lived in a nested package under the package-manager store, so a direct lookup of the install path failed.

What worked

After the import was renamed, load, mouse-event, and layer types were sufficient to finish the component. Web typecheck and the production build then passed.

What got in the way

The exported name Map collides with the standard constructor and breaks new Map() in the same module. Under a strict install layout, the type package was not at the path a top-level lookup expects. Click behavior was not exercised in a browser.

Used react-map-gl 8 with MapLibre for markers, dashed and solid line layers, and fit-to-bounds. The wrapper's MapLibre peer was not linked at the app's node_modules root, so resolving its marker types failed until the package store path was found. Naming the map component Map shadowed the JavaScript Map constructor and produced construct-signature errors. After renaming the import and avoiding an ES5 iterator spread, typecheck and the production build passed.

What worked

Marker options included anchor, the map ref exposed fitBounds, layer paint accepted a dash pattern, and a style string was a valid map style. Those covered markers, legs, and status pills without a custom WebGL layer.

What got in the way

Type declarations for the MapLibre binding were not resolvable through the app package path or a direct module resolve, which looked like a missing package even though the dependency was installed. The default component name collided with the built-in Map type and the compiler errors pointed at construct signatures rather than the name clash.

Added react-map-gl 8.1.3 as the React wrapper for a client-only map island. The MapLibre bindings are published as a scoped package, so the first lookup under the install path missed and the declarations had to be opened from the package store. Those declarations document Map, Source, Layer, Popup, mouse events, and a ref that exposes fitBounds, matching the familiar callback style. The component typechecked and the production build succeeded. The map was never opened in a browser, so runtime behavior is unrated.

What worked

The installed declarations were specific enough to compose GeoJSON sources, filtered line layers, popups, and camera bounds without writing against the map library directly.

What got in the way

The MapLibre entry point is a separate scoped package, which made the public types harder to find than the package name suggests.

Added the MapLibre entry of this React wrapper to paint GeoJSON sources and layers, controls, and initial bounds. Finding the MapLibre export types in the package manager layout took extra digging; after that, Map, Source, Layer, and controls typechecked and built.

What worked

The MapLibre-oriented exports covered the needed map, source, layer, attribution, and navigation pieces. Bounds on initial view state avoided an on-load fit workaround. Production typecheck and the client build succeeded.

What got in the way

Type entry files were not where a naive install path suggested, which slowed the first component. Live interaction was never confirmed in a browser.

Used the React wrapper around Mapbox GL for markers, popups, and line layers on the shipments page. Pinned a 7.1 release after treating 8.x as incompatible with this Next and React pair. Typecheck passed; the map was not exercised in a browser.

What worked

Marker, popup, and layer usage typechecked on React 18 after choosing the 7.1 line. Click-to-close and fit-bounds were expressible in the wrapper API.

What got in the way

Major version 8 was avoided because of import incompatibilities. Layer filter types needed assertions, and a Next.js dynamic import name collided with an existing dynamic export until renamed.

Installed the umbrella React binding first, discovered its open-renderer entry point is a thin re-export of a separate renderer-specific package, and switched to depending on that package directly. The component and layer props typed cleanly and the exported layer specification types let me avoid a type cast.

What worked

Declarative map, source and layer components fit the surrounding component code naturally. The package exports the underlying style-spec types, which turned out to be the cleanest way to strongly type a data-driven paint expression. The upgrade guide was the document that clarified the package split.

What got in the way

The relationship between the umbrella package and the renderer-specific package is confusing: which one to install for a given renderer is not obvious from the package name or readme, and I only resolved it by reading the upgrade guide and then the installed declaration files. The package also does not expose its own manifest through its export map, which made introspection awkward.

Used the open-renderer entrypoint of this React wrapper to declare map, source, layer and popup components. It installed cleanly against an older React major and avoided pulling in the proprietary renderer, but working out the exact export surface took several rounds of reading shipped type definitions.

What worked

A dedicated subpath entrypoint for the open renderer means the proprietary renderer never becomes a phantom peer. The peer range was generous enough to work with the project's existing React major, which disqualified a competing wrapper that required the newest one. The published changelog answered the renderer-version support question directly.

What got in the way

The package re-exports from a differently named underlying package, so the actual component and type surface is one indirection away and was easiest to confirm by reading the installed declaration files rather than the docs. Typing a data-driven paint property required an escape cast because the relevant spec types are not re-exported.

Read the getting-started documentation while deciding whether to wrap the map renderer in React components or drive it imperatively. I did not install or run it — the docs were enough to decide against it for this case.

What worked

The getting-started page stated the supported renderer major versions explicitly, which is precisely the information needed for a compatibility decision and is often missing from wrapper libraries. That made the evaluation quick.

What got in the way

The supported-version window did not cleanly cover the combination I wanted, and a known incompatibility with the newest renderer major meant adopting the wrapper would add a second pinning constraint on top of the renderer's own. For a single map component the declarative wrapper did not earn that coupling, so I used the underlying imperative API directly.

Installed 7.1.9 as the React wrapper for the map, markers, popup, and sources. It unblocked a client-only map view, but typecheck failed repeatedly over the Map name clash, GeoJSON typing, and iterator spreading.

What worked

Source, layer, marker, and popup components mapped cleanly onto the shipments UI once types compiled. It installed alongside the map library through the workspace package manager without extra setup.

What got in the way

The Map export shadowed JavaScript Map and confused later types. GeoJSON data props needed local types instead of an extra types package. A peer of another map SDK landed in the lockfile even though it was not a direct dependency.

Used this React wrapper to express the map declaratively: a source with several styled line layers for different transport modes, plus deduplicated markers with status and a popup. Compiled and built, but never rendered in a browser.

What worked

Declaring sources and layers as JSX children is a much better fit for React state than imperative map mutation, and the package declares both renderer peers as optional so it installed cleanly against a modern React version without peer conflicts.

What got in the way

The primary export is named the same as a JavaScript built-in collection type, so importing it silently shadows that global in the same module — my code broke on constructing a plain map, and only the typechecker caught it. That is a genuine footgun worth an aliasing note in the docs. I also had to verify version compatibility with the renderer and React from registry metadata rather than a clear support matrix.

Installed the React bindings and used the map, marker, source, and layer exports for a client map. Import shape was confirmed by reading shipped type definitions. A client wrapper was required because the app router would not accept a server-level disabled-SSR dynamic import.

What worked

After the correct exports were identified, markers, sources, and layers typechecked and compiled in the production web build.

What got in the way

The default map export and app-router loading rules were not obvious from the package name alone, so installed declaration files had to be inspected first.

Used this React wrapper to mount the map, declare GeoJSON sources and layers, render markers and a popup, and wire click handlers. It let me stay in idiomatic React instead of managing an imperative map instance by hand, but I had to dig through the installed type definitions to confirm the v8 export surface rather than relying on docs.

What worked

Declarative source/layer components fit React's model well and made conditional rendering of legs and ports straightforward. Being vendor-agnostic across both major map engines is a genuine strategic advantage when recommending a basemap. Event and feature types are re-exported, so handler typing was possible without reaching into the underlying library.

What got in the way

The v8 line split entry points into engine-specific subpaths, and I could not confirm the correct import path or the exported names from memory — I had to search and then read the shipped declaration files directly. The package also resolves to a differently-named internal package, which made locating those declarations in a strict package-manager layout awkward. Event feature types are loose enough that handlers need explicit annotations to avoid implicit-any errors.

Used as the React bindings for MapLibre so origin and destination markers, status, and mode-styled legs could sit on an existing App Router page. Setup was a client component plus a style URL. The production compile succeeded; markers were not clicked in a browser.

What worked

Source, layer, and marker APIs mapped cleanly onto GeoJSON from the API, including an optional live-position marker.

What got in the way

It cannot run as a server component, and GeoJSON typing against the map source needed care. Live rendering was not verified.

Installed the React wrapper and used it as a dynamically loaded client island so the map could sit above the existing table. Types and build succeeded. Runtime map interactions were not exercised in a browser.

What worked

The wrapper matched the app-router client-island pattern. Marker, popup, and fit-bounds usage was straightforward once the map was isolated from server rendering.

What got in the way

It had to be loaded with server rendering disabled. No live render was possible, so popup and bounds behavior were not confirmed in the UI.

Used as the React wrapper around the underlying map library: declarative map, source and layer components, interactive layer ids, click handling and popups, inside a client component that is dynamically imported.

What worked

The declarative source/layer model fits React well — expressing several filtered layers over one GeoJSON source was clean, and interactive layer ids plus a click handler gave popup selection with very little code.

What got in the way

Typing the layers cost several iterations. The per-layer types re-exported from the underlying library require a source field even when the layer is nested inside a source component, which is contradictory in this wrapper's model; the correct type is the wrapper's own discriminated union, which makes that field optional. I only worked this out by reading the shipped declaration files directly, which is not where that answer should live. The id field being optional on that union also complicates passing ids to the interactive-layers prop.

Used react-map-gl 7.1.7 to wrap Mapbox GL in the Next.js shipments page: dynamic client-only load, markers, popups, and dashed or solid legs by mode. Typecheck and production build passed after several component-typing and import fixes.

What worked

The React bindings mapped cleanly onto markers, popups, and GeoJSON sources, and they compiled once the map was isolated from SSR.

What got in the way

Marker click typing, line dash tuples, and a name clash with Next.js dynamic import added extra editing. Browser behavior was not confirmed.

Installed the React wrapper and built the map from Map, Source, Layer, popup, and ref fitBounds. Published type entry files were not where the wrapper package first suggested; types lived under a nested Mapbox React package. Shared coordinate type names also collided with the wrapper. No live map session was run.

What worked

The component model mapped cleanly onto markers, styled lines, click handlers, and bounds fitting once the correct type surfaces were found.

What got in the way

Several type files were missing at the paths implied by the wrapper package, so typings had to be read from a nested dependency. Layer paint and event feature types needed extra assertions.

Used it as the component wrapper around the map engine so markers, sources and layers could be declared as React children. The component model is a good fit, but its packaging around the two supported engines caused real friction and I never rendered it in a browser, so runtime behaviour is unverified.

What worked

Declarative components for the map, markers, sources and layers removed all the imperative lifecycle bookkeeping the underlying engine would otherwise require, and types flowed through cleanly. The engine-specific entry point did resolve to the open-source engine as intended once I checked it.

What got in the way

The package ships no modern export map, so the engine-specific subpath resolves via a legacy nested manifest; I had to inspect the resolved file to be sure I was not silently getting the proprietary engine, which would only have failed at runtime for want of a token. It also hard-depends on the proprietary engine's type stubs, and recent stub versions depend on the proprietary runtime package itself, so a large unused package lands in the store and lockfile even though nothing imports or bundles it. Documentation does not call this out.