Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

chore: update upgrade guide 3.3 (#3521)

Igor Dykhta3831ee3ba96c
diff --git a/UPGRADE-GUIDE.md b/UPGRADE-GUIDE.md
index 401ddf465..43b3f41c9 100644
--- a/UPGRADE-GUIDE.md
+++ b/UPGRADE-GUIDE.md
@@ -2,14 +2,32 @@
## Table of Content
+- [v3.2 to v3.3](#upgrade-from-v32-to-v33)
+- [v2.4 to v3.0](#upgrade-from-v24-to-v30)
- [v2.3 to v2.4](#upgrade-from-v23-to-v24)
-
- [v2.2 to v2.3](#upgrade-from-v22-to-v23)
- [v2.1 to v2.2](#upgrade-from-v21-to-v22)
- [v2.0 to v2.1](#upgrade-from-v20-to-v21)
- [v1.1.12 to v2.0](#upgrade-from-v1112-to-v20)
- [v1.1.11 to v1.1.12](#upgrade-from-v1111-to-v1112)
+## Upgrade from v3.2 to v3.3
+
+See the full upgrade guide: **[Upgrade Guide — kepler.gl 3.3](docs/upgrade-guide-v3.3.md)**
+
+### Highlights
+
+- **React 19** — kepler.gl now requires `react@^19.0.0` and `react-dom@^19.0.0`. React 18 is no longer supported.
+- **react-redux v9** — upgraded from `^8.0.5` to `^9.1.0`
+- **react-intl v7** — upgraded from `^6.3.0` to `^7.0.0`
+- **react-map-gl 8 / maplibre-gl 4** — new `@vis.gl/react-maplibre` peer dependency
+- **deck.gl 9 / luma.gl 9** — major rendering stack upgrade
+- **Node.js 20** — minimum raised from 18.18.2 to 20.19.3
+- **TypeScript 5.6** — upgraded from 4.7.2
+- **HeatmapLayer** — rewritten from Mapbox GL to deck.gl base
+- **`layerOrder`** — type changed from flat `string[]` to `(string | LayerOrderGroup)[]`
+- **`LayerSelectorPanelFactory`** — removed from `@kepler.gl/components`
+
## Upgrade from v2.4 to v3.0
- TBD
diff --git a/docs/upgrade-guide-v3.3.md b/docs/upgrade-guide-v3.3.md
index b56258544..292a6f08c 100644
--- a/docs/upgrade-guide-v3.3.md
+++ b/docs/upgrade-guide-v3.3.md
@@ -6,16 +6,25 @@ kepler.gl 3.3 upgrades the rendering stack from **deck.gl 8 / luma.gl 8** to **d
| Package group | Old version | New version |
| --------------- | ----------- | ----------- |
+| `react` | ^18.2.0 | **^19.0.0** |
+| `react-dom` | ^18.2.0 | **^19.0.0** |
+| `react-redux` | ^8.0.5 | **^9.1.0** |
+| `react-intl` | ^6.3.0 | **^7.0.0** |
+| `react-map-gl` | ^7.1.6 | **^8.1.1** |
+| `maplibre-gl` | ^3.6.2 | **^4.0.0** |
| `@deck.gl/*` | 8.9.x | **9.2.11** |
| `@luma.gl/*` | 8.x | **9.2.6** |
| `@loaders.gl/*` | 3.x / 4.3.2 | **4.3.4** |
| `math.gl` | — | **^4.1.0** |
| `typescript` | 4.7.2 | **5.6.3** |
+| Node.js | >=18.18.2 | **>=20.19.3** |
### New dependencies
| Package | Version | Notes |
| ------------------------------------ | ------- | --------------------------------------------- |
+| `@vis.gl/react-maplibre` | 8.1.1 | MapLibre bindings for react-map-gl 8 |
+| `maplibregl-mapbox-request-transformer` | ^0.0.2 | Mapbox-style URL transform for MapLibre |
| `@deck.gl-community/editable-layers` | 9.2.8 | Replaces `@nebula.gl/layers` for editor layer |
| `@deck.gl-community/layers` | 9.2.8 | Community layers package |
| `@deck.gl/widgets` | 9.2.11 | New deck.gl 9 module |
@@ -35,6 +44,135 @@ All `@deck.gl/*`, `@loaders.gl/*`, and `@luma.gl/*` packages are pinned via reso
---
+## Breaking Changes — React 19
+
+kepler.gl 3.3 requires **React 19**. React 18 is no longer supported.
+
+```sh
+npm install react@^19.0.0 react-dom@^19.0.0 react-redux@^9.1.0
+```
+
+### Removed legacy lifecycle methods
+
+All usage of deprecated lifecycle methods (`componentWillReceiveProps`, `componentWillMount`) has been removed. If you have custom components extending kepler.gl internals that rely on these methods, migrate them to `componentDidUpdate`, `getDerivedStateFromProps`, or hooks.
+
+### `ref` handling
+
+React 19 passes `ref` as a regular prop. If you have custom wrapper components using `React.forwardRef` around kepler.gl components, these will still work but `forwardRef` is no longer required for new components.
+
+### Strict Mode
+
+React 19 enforces stricter Strict Mode behavior. If your application uses `<React.StrictMode>`, you may notice double-invocation of effects during development. This does not affect production builds.
+
+### `react-redux` v9
+
+The upgrade to `react-redux@^9.1.0` drops the legacy context API. Ensure you are not relying on the removed `store` prop passed directly to connected components — use `<Provider store={store}>` at the root instead.
+
+### `react-intl` v7
+
+`react-intl` is upgraded to v7. If your app provides custom format configurations or uses `intlShape`, consult the [react-intl 7.x migration guide](https://formatjs.github.io/docs/react-intl/upgrade-guide-7x/).
+
+### Upgrading custom components
+
+If you use kepler.gl's dependency injection to replace built-in components:
+
+1. Replace any class components with function components using hooks
+2. Remove `defaultProps` declarations — use default parameter values instead
+3. Update any `propTypes` usage (still functional but no longer shipped with kepler.gl)
+
+---
+
+## Breaking Changes — Map Libraries
+
+### react-map-gl 8 and maplibre-gl 4
+
+`react-map-gl` is upgraded from `^7.1.6` to `^8.1.1`, and `maplibre-gl` from `^3.6.2` to `^4.0.0`. A new dependency `@vis.gl/react-maplibre` (`8.1.1`) has been added.
+
+```sh
+npm install react-map-gl@^8.1.1 maplibre-gl@^4.0.0 @vis.gl/[email protected]
+```
+
+If your application imports from `react-map-gl` directly (e.g., for custom map overlays), review the [react-map-gl 8.x upgrade guide](https://visgl.github.io/react-map-gl/docs/upgrade-guide) for API changes.
+
+### maplibre-gl 4
+
+maplibre-gl v4 includes breaking changes to the style specification and internal rendering pipeline. If you use `maplibregl` directly or supply custom map styles, consult the [maplibre-gl v4 changelog](https://github.com/maplibre/maplibre-gl-js/blob/main/CHANGELOG.md).
+
+---
+
+## Breaking Changes — Node.js
+
+### Minimum Node.js version raised to 20
+
+The minimum required Node.js version is now **20.19.3** (previously 18.18.2). Update your CI and development environments accordingly:
+
+```sh
+nvm install 20
+nvm use 20
+```
+
+---
+
+## Breaking Changes — Layers
+
+### HeatmapLayer rewritten from Mapbox GL to deck.gl
+
+`HeatmapLayer` no longer extends `MapboxGLLayer`. It now extends the base `Layer` class and renders using a deck.gl-based implementation.
+
+**Impact:**
+- If you extended `HeatmapLayer` or relied on its Mapbox GL internals, your subclass will break.
+- The layer config type changed from `MapboxLayerGLConfig` to `LayerBaseConfig`.
+- New visual config properties: `intensity`, `threshold`, `aggregation`.
+- A new column mode `COLUMN_MODE_GEOJSON` is supported.
+
+If you have custom code that checks `layer instanceof MapboxGLLayer` for heatmap layers, update it to check `layer instanceof Layer` or use `layer.type === 'heatmap'`.
+
+### `layerOrder` type changed
+
+The `layerOrder` property in `visState` changed from a flat `string[]` to `LayerOrderEntry[]`, where:
+
+```typescript
+type LayerOrderGroup = {
+ id: string;
+ label: string;
+ isVisible: boolean;
+ layerOrder: LayerOrder;
+ isIncludedInLegend: boolean;
+};
+type LayerOrderEntry = string | LayerOrderGroup;
+type LayerOrder = LayerOrderEntry[];
+```
+
+If your application reads or manipulates `state.keplerGl.*.visState.layerOrder` directly (e.g., for custom layer reordering), update your code to handle mixed arrays of layer IDs and group objects. Use the helper `getFlatLayerOrder(layerOrder)` from `@kepler.gl/utils` to get a flat list of layer IDs.
+
+---
+
+## Breaking Changes — Removed Exports
+
+### `LayerSelectorPanelFactory` removed
+
+`LayerSelectorPanelFactory` is no longer exported from `@kepler.gl/components`. If you were using dependency injection to replace this factory, the functionality has been reorganized — use the layer list panel and layer group components instead.
+
+### `setLayerBlending` removed
+
+The function `setLayerBlending` (previously exported from `@kepler.gl/utils`) is removed. Use `getLayerBlendingParameters` instead, which returns a `parameters` object for deck.gl 9.
+
+---
+
+## Breaking Changes — Behavior
+
+### `preserveDrawingBuffer` disabled by default
+
+The base map's WebGL context previously set `preserveDrawingBuffer: true` unconditionally. It is now **`false` by default** and only enabled during image/video export (`isExport: true`).
+
+**Impact:** If your application calls `canvas.toDataURL()` or `canvas.toBlob()` on kepler.gl's map canvas outside of the built-in export flow, the canvas will now return blank data. To restore the old behavior, pass `preserveDrawingBuffer: true` via `bottomMapContainerProps` in your `MapContainer` override.
+
+### `GEOCODER_ICON_SIZE` constant changed
+
+`GEOCODER_ICON_SIZE` changed from `80` to `160` to compensate for anchor normalization in the new rendering stack. If you import this constant for custom geocoder styling, the rendered pin size should remain the same visually — but if you used the raw value for calculations, update accordingly.
+
+---
+
## Breaking Changes for Library Consumers
### 1. WebGL context callback renamed
@@ -183,6 +321,40 @@ A new **3D Tile Layer** enables rendering of photogrammetry meshes, buildings, t
Add a 3D tileset via the **Add Data → Tilesets** modal by selecting the "3D Tile" type. The layer supports opacity, point size configuration, zoom-to-layer, and the Light and Shadow effect. See the [3D Tile Layer user guide](./user-guides/c-types-of-layers/p-3d-tile-layer.md) for details.
+### Flow Layer
+
+A new **Flow Layer** renders origin-destination flows as animated arcs with directional particles.
+
+### Bitmap Overlay Layer
+
+A new **Bitmap Overlay Layer** renders georeferenced raster images (PNG, JPEG) on the map.
+
+### Swipe Compare Mode
+
+A new map split mode (`MapSplitMode.SWIPE_COMPARE`) enables side-by-side comparison of layers using a draggable divider. Use the `setMapSplitMode` action to switch between `SINGLE_MAP`, `DUAL_MAP`, and `SWIPE_COMPARE`.
+
+### Annotations
+
+A new annotation system allows adding text labels, markers, and shapes directly on the map. New actions: `addAnnotation`, `removeAnnotation`, `updateAnnotation`, `duplicateAnnotation`, `setSelectedAnnotation`.
+
+### Layer Groups
+
+Layers can now be organized into named groups with shared visibility and legend controls. New actions: `addLayerGroup`, `removeLayerGroup`, `updateLayerGroup`, `addLayerToLayerGroup`, `removeLayerFromLayerGroup`.
+
+### Other New Features
+
+- **Zoom and compass controls** — on-map navigation buttons
+- **Tooltip toggle** — ability to disable tooltips per-map
+- **Higher pitch option** — configurable maximum pitch beyond the default 60°
+- **GeoJSON mode for aggregation layers** — aggregate by polygon geometry
+- **Labels for GeoJSON layer** — text label support on polygon/line features
+- **Rectangle drag-to-filter** — streamlined rectangular area filter
+- **Layer visibility toggle in map legend**
+- **Locale persistence** — locale is included in exported maps and restored on load
+- **Video export with effects** — post-processing effects are captured in video export
+- **Non-linear piecewise focus range** for VisConfig sliders
+- **CSV/TSV auto-delimiter detection** in data processors
+
### Fog post-processing effects
Two new post-processing effects are available: