MapLibre Migration Lint — Mapbox GL JS v2+

$950 a month: that is what the Mapbox price list charges a web app for 300,000 Mapbox GL JS map loads, and every front-end developer who upgraded mapbox-gl past 1.x is on that meter. This guide is for teams in the US, the EU and anywhere else who ship store locators, delivery maps or dashboards on Mapbox GL JS v2 or v3 and want to move to MapLibre GL JS.

What Mapbox changed, and when

mapbox-gl v2.0.0 was published on 8 December 2020. Its changelog opens with the breaking change: mapbox-gl-js is no longer under the 3-Clause BSD license, and by upgrading you agree to the Mapbox terms of service. The LICENSE.txt in the repository now says the SDK may be used only by developers with a current active Mapbox account. The same release made a Map object initialisation a billable map load.

The price list for Mapbox GL JS map loads is tiered: up to 50,000 a month free, then $5.00 per 1,000 up to 100,000, $4.00 up to 200,000, $3.00 up to 1,000,000 and $2.50 up to 5,000,000. For 300,000 loads that is 50,000 free, $250, $400 and $300: $950 a month.

Version 1.13.3 is the last BSD release of mapbox-gl. MapLibre GL JS was forked from 1.13 and is still BSD-3-Clause.

Why a rename is not a migration

The obvious move is to replace mapbox-gl with maplibre-gl in package.json and in the import. The map then fails in quieter ways:

• MapLibre GL JS 2.0.0 removed accessToken and every mapbox:// URL. A style of mapbox://styles/mapbox/streets-v12 loads a blank canvas.
• MapLibre 3.0.0 removed the old mapboxgl- CSS classes. A selector like .mapboxgl-ctrl-top-right now matches nothing.
• map.setFog() does not exist in MapLibre; sky and fog live in map.setSky().
• The Mapbox geocoder plugin still sends every search to the Mapbox Geocoding API with your token.
• A static image URL with access_token=pk. still bills Mapbox.

What the lint found in a real-shaped file

We ran MapLibre Migration Lint on a sample store-locator.js: a Mapbox GL JS v3 page with a geocoder, a draw control, fog, a vector source and a static thumbnail. It gave 13 findings from 11 of the 17 rules: 3 errors, 9 warnings and 1 info. The errors were the access token, the mapbox:// style and the mapbox:// tileset. The warnings covered the import, the CSS, the geocoder, three uses of the mapboxgl global, setFog, the mapboxgl- selector and the api.mapbox.com URL. The info note was mapbox-gl-draw, which runs on MapLibre once its control classes point at maplibregl-ctrl.

The MapLibre version of the same file gave 0 findings.

The fix, line by line

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
const map = new maplibregl.Map({ container, style: 'https://demotiles.maplibre.org/style.json' });
map.setSky({ 'fog-color': 'rgb(220, 230, 240)' });

React apps on react-map-gl 8 import Map from 'react-map-gl/maplibre' and drop mapboxAccessToken. Lockfiles matter too: a loose range or a transitive dependency can still resolve mapbox-gl 3.x, so the lint reads package-lock.json and yarn.lock.

One caveat

Changing the library ends the Mapbox licence on your bundle. It does not end Mapbox billing if the style or tiles still come from api.mapbox.com. The token and API URL rules point at exactly those lines, so you know what is left to move.

Try it

The web version runs the same engine in the browser: paste a file and read the findings. The VS Code extension checks the open file for free and offline.