MapLibre GL JS

MapLibre GL JS is an open-source JavaScript library for publishing interactive maps on websites and webview-based apps, using GPU-accelerated vector tile rendering for smooth panning, zooming, and rotation. It originated as a community fork of mapbox-gl-js after Mapbox moved to a non-OSS license in December 2020, and has since evolved well beyond drop-in compatibility with new capabilities like 3D terrain, globe projection, and custom WebGL layers.

The library exposes a Map class as its central entry point, backed by a style-driven rendering pipeline (vector tiles, raster tiles, GeoJSON, images, video) and a worker-based tile-processing architecture that keeps the main thread responsive. It ships as an ESM/CJS bundle with full TypeScript typings and integrates with React, Angular, and other frontend stacks via community bindings.

What You Get

• A Map class with a declarative, JSON-based style specification for controlling every visual layer (fill, line, symbol, raster, heatmap, hillshade, background, custom layers)
• Built-in navigation, geolocation, scale, fullscreen, terrain, and globe UI controls, plus draggable markers and popups
• Support for vector tiles, raster tiles, GeoJSON sources (with clustering), image/video overlays, and 3D terrain/hillshade rendering
• A CustomLayerInterface for injecting raw WebGL rendering code directly into the map’s render pipeline
• A worker-pool architecture that offloads tile parsing and geometry tessellation off the main thread to keep interactions smooth
• First-class TypeScript typings and an addProtocol API for intercepting and customizing tile/resource fetches (e.g. PMTiles)

Common Use Cases

• Embedding an interactive, self-hosted or vendor-neutral map in a web application without paying per-load API fees
• Building GIS and data-visualization dashboards that render large GeoJSON datasets, choropleths, or heatmaps over a basemap
• Rendering 3D terrain, hillshading, and globe-projection views for outdoor, aviation, or geospatial-analysis tools
• Replacing mapbox-gl-js in existing codebases that need to stay on an OSS license
• Building custom WebGL visualizations (weather layers, satellite imagery, real-time tracking) on top of a maintained tile-rendering core via CustomLayerInterface

Under The Hood

Architecture - The library is organized around a central Map class (src/ui/map.ts, ~4,500 lines) that owns a Style (src/style/style.ts), a Transform/camera model, and a Painter (src/render/painter.ts) that issues the actual WebGL draw calls each frame. Data flows from tile sources (vector, raster, GeoJSON, raster-DEM, image, video — each in src/source/) through a worker pool (src/util/dispatcher.ts, src/util/actor.ts) that parses and tessellates tile geometry off the main thread, then hands prepared buffers back to the painter for rendering against the active style’s paint/layout properties. Style layers (fill, line, symbol, raster, hillshade, background, custom) each define their own bucket/program pairing, and a CustomLayerInterface lets host applications splice raw WebGL calls directly into this render loop, giving the architecture a plugin-like extension point without forking the renderer.

Tech Stack - Written entirely in TypeScript (~88% of the codebase) with a small amount of GLSL for shaders (2.4%) and CSS for UI chrome. Core dependencies are deliberately narrow and mostly maintained under the @maplibre or @mapbox scopes: @maplibre/maplibre-gl-style-spec for style validation, @maplibre/geojson-vt and @mapbox/vector-tile for tiling, earcut for polygon triangulation, gl-matrix for linear algebra, and pbf for protobuf decoding of vector tiles. The project builds with Rolldown, tests with Vitest across separate unit/integration/build/render configs, lints with ESLint and Stylelint, and generates its public typings via a dedicated generate-typings build step, publishing both ESM (dist/maplibre-gl.mjs) and full TypeScript declaration files.

Code Quality - The repository pairs almost every implementation file with a co-located *.test.ts (198 test files against 299 non-test source files), plus a separate integration suite (test/integration) and a dedicated render-regression suite (test/integration/render) that diffs rendered pixel output against reference images — a strong signal for a WebGL rendering library where visual regressions are otherwise easy to miss. Naming is consistent and domain-driven (geojson_source.ts, raster_dem_tile_worker_source.ts), error handling uses typed custom errors (AJAXError, GPUInitializationError), and the npm test script chains linting, unit, integration, render, and build tests together as a single CI gate.

API Design - The public surface is a single Map constructor plus a family of well-named control, source, and event classes, all re-exported from one src/index.ts entry point with full TypeScript types attached to every option object (MapOptions, StyleOptions, FlyToOptions, etc.). Getting started requires only a container element and a style URL/object, and the event system follows a consistent Evented/on/off pattern shared across Map, Popup, and Marker. The tradeoff for this breadth is a large API surface (dozens of exported types and control classes) and the style specification’s own JSON-schema learning curve, partially offset by extensive generated docs and a large official example gallery.