MapLibre GL JS: a community fork of mapbox-gl-js for GPU-rendered vector tiles

What problem MapLibre GL JS solves, and who ends up using it

MapLibre GL JS is a JavaScript and TypeScript library for publishing maps on websites or webview based apps. The README states that fast display comes from GPU-accelerated vector tile rendering, which is the whole point: instead of pre-rendered raster tiles, the browser receives vector data, parses it, and draws it with WebGL2. That lets a style change colour, filter or label placement at runtime without a new tile request.

The library began as an open-source fork of mapbox-gl-js before that project switched to a non-OSS licence in December 2020. The README says the 1.x versions were intended as a drop-in replacement for the Mapbox OSS 1.x line with additional functionality, and that the code has evolved a lot since. That history explains the audience: teams that had a Mapbox GL JS integration and wanted to keep the same programming model under a permissive licence.

Who it is for, concretely. You are building a web map that needs camera control, layers, markers, 3D terrain or 3D buildings, and you are willing to supply a style document and a tile endpoint. It is not for someone who wants an embeddable map widget with nothing else to configure. The README points at a demo style at demotiles.maplibre.org, which is a demonstration endpoint, not a production basemap contract.

How the rendering pipeline is put together

The package.json tells you more about the architecture than the README does. The runtime dependencies include @mapbox/vector-tile and @maplibre/vt-pbf for decoding and encoding vector tiles, @maplibre/geojson-vt for turning GeoJSON into tiles, earcut for polygon triangulation, gl-matrix for the camera math, kdbush and tinyqueue for spatial indexing and prioritisation, potpack for atlas packing, and @mapbox/tiny-sdf for glyph rendering. @maplibre/maplibre-gl-style-spec is the style document definition, split out as its own package. @maplibre/mlt appears in the dependency list as well.

That list is the data flow. A style JSON names sources and layers. Sources point at tile URLs. Tiles arrive as protobuf, get decoded by the vector-tile and pbf packages, are indexed spatially, and are then drawn as GPU geometry assembled through earcut and gl-matrix. Text and icons are packed into atlases with potpack; glyphs are rasterised with tiny-sdf. The style spec package is what validates the document you hand to the Map constructor.

The repository layout confirms the split: src/ for the library, build/ and rolldown.config.ts for bundling, test/ with separate vitest configurations for unit, integration, build and benchmark runs (vitest.config.unit.ts, vitest.config.integration.ts, vitest.config.build.ts, vitest.config.bench.ts), and an ARCHITECTURE.md at the top level. The output is an ES module at dist/maplibre-gl.mjs with types at dist/maplibre-gl.d.ts, plus a separate CSS file at dist/maplibre-gl.css. The package declares "type": "module" and lists *.css and src/**/*.ts under sideEffects, which matters if your bundler tree-shakes aggressively: the CSS import must survive.

Installing MapLibre GL JS and drawing a first map

The README gives a CDN path with no build step. Put the stylesheet in the head of your HTML file, then a container div and a module script in the body. The stylesheet link is:

<link href='https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css' rel='stylesheet' />

Then the container and the map itself. The README's example uses the unpkg ESM build directly, so the import is a URL rather than a bare specifier:

<div id='map' style='width: 400px; height: 300px;'></div>
<script type='module'>
import * as maplibregl from 'https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.mjs';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [-74.5, 40],
  zoom: 9
});
</script>

After that you should see a 400 by 300 map centred on longitude -74.5, latitude 40 at zoom 9. Note the two fields that decide everything later: container names the div id, and style is a URL to a style document. If the style URL is unreachable, you get an empty canvas, not an error dialog.

If you are bundling, the package is published as maplibre-gl on npm with the module entry at dist/maplibre-gl.mjs and the style entry at dist/maplibre-gl.css. The repository also ships a docker-compose.yml for people who do not want a local Node setup. The comment in that file states that one command builds the library and serves the examples, and that node_modules lives in a named volume so the host tree is untouched:

docker compose run --rm --service-ports dev

After that the comment says to open http://localhost:9966/test/examples/. The same file defines a docs service and a docs-serve service on port 8000, both using the zensical/zensical:0.0.62 image with a strict build.

Where MapLibre GL JS is the wrong tool

The library renders; it does not supply map data. The README's example style points at demotiles.maplibre.org, and nothing in the repository describes that endpoint as a production tile service. If your plan is to install the package and have a working world map under a commercial traffic load, you are missing a component: either a self-hosted vector tile stack or a commercial tile provider. The style document is also yours to write or obtain, and the style spec is a separate package with its own version line (@maplibre/maplibre-gl-style-spec ^26.4.4 in this release), so a style written for one spec version is not automatically valid for another.

WebGL2 is the second boundary. The repository topics list webgl2 explicitly, and GPU rendering is the mechanism the README cites for speed. That mechanism requires a browser and device that expose WebGL2. Where that is absent, this library is the wrong choice rather than a slow one.

Third, the maintenance model is community-led. The README's contribution section asks people who depend on a free software alternative to mapbox-gl-js to join the effort, and notes that the project already combines a few early fork efforts. That is honest and it also means there is no vendor SLA behind the renderer. If your organisation needs a support contract attached to the map library itself, the licence and the governance here do not provide one.

Finally, if your map is a handful of markers over a static image, or your data is small enough that an SVG or a raster tile layer is fine, the vector pipeline is overhead you will pay for in bundle size, style authoring and tile infrastructure.

MapLibre GL JS compared with Leaflet

The comparison people search for is MapLibre GL JS vs Leaflet, and the difference is architectural rather than cosmetic. Leaflet is a DOM and raster tile library: it positions image tiles and HTML elements in the page. MapLibre GL JS decodes vector tiles and draws them on the GPU through WebGL2. That is why the dependency list contains earcut, gl-matrix and tiny-sdf rather than DOM helpers.

The practical consequences follow. In MapLibre GL JS, changing a layer's colour or a filter is a style edit applied at render time; in a raster approach the server has to produce a different image. MapLibre GL JS gives you camera pitch and bearing, 3D terrain and 3D buildings, as the README's example gallery shows. The cost is a style document, a vector tile source, and a WebGL2 requirement. Leaflet's cost is lower: raster tiles from almost anywhere, and rendering that works where WebGL2 does not.

There is a second comparison in the same family: MapLibre GL JS vs OpenLayers, and MapLibre GL JS vs Mapbox GL JS. Against Mapbox GL JS the lineage is direct, since this library forked from it, and the README frames the split as a licensing event rather than a technical one. Against OpenLayers the difference is scope: MapLibre GL JS is a vector tile renderer with a style specification, not a general projection and format toolkit. If your requirement is exotic projections or a long list of OGC formats, the vector renderer is not the tool you are looking for.

Maintenance, versioning and what the licence does and does not cover

The last push to the default branch was on 2026-09-21, and the most recent releases listed are v6.10.0 on 2026-09-15, v6.9.1 on 2026-09-14 and v6.9.0 on 2026-09-09. The repository is not archived. That is a dense release cadence on the 6.x line, and the README states the project follows Semantic Versioning (2.0.0), so major versions are where breaking changes are supposed to land.

Upgrade cost is dominated by two things. First, the style spec is versioned separately from the library, so a library bump can pull a spec bump with it; the dependency here is @maplibre/maplibre-gl-style-spec ^26.4.4. Second, the package is ESM-only in its exports map: the "." entry exposes types at ./dist/maplibre-gl.d.ts and import at ./dist/maplibre-gl.mjs, with no require condition. A CommonJS consumer cannot simply require it. That is a build-system decision to make before adoption, not after.

On licensing: the package.json declares "license": "BSD-3-Clause" and the README carries a BSD 3-Clause badge, while the repository metadata reports NOASSERTION, which is GitHub's classifier failing to match the file rather than a different licence. The BSD 3-Clause text is in LICENSE.txt at the top level. That covers the library code. It does not cover the tiles you request, the style you load, or the fonts and sprites those reference; the demo style at demotiles.maplibre.org is a separate service with its own terms. This is not legal advice, and the licence file is the document that governs.

Editorial conclusion

Adopt MapLibre GL JS if you want a BSD-3-Clause renderer you can read and patch, and you already have or intend to buy a vector tile source. Do not adopt it expecting a hosted basemap: the repository ships the renderer and a demo style, not map data. Before committing, verify three things in your own environment: that your target browsers expose WebGL2, that your style JSON validates against @maplibre/maplibre-gl-style-spec, and that your tile provider's terms cover your traffic. Then pin the version, because the project follows Semantic Versioning and the current line is 6.x.

Frequently asked questions

Official sources

1. Issues
2. maplibre/maplibre-gl-js on GitHub
3. Project website
4. README
5. Releases