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.mdindex 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- TBDdiff --git a/docs/upgrade-guide-v3.3.md b/docs/upgrade-guide-v3.3.mdindex 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, tAdd 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 effectsTwo new post-processing effects are available: