Skip to content

Introduction

Leaflet GL is a custom mapping library that combines Leaflet and MapLibre GL JS. It is part of the Windy.com frontend codebase and was designed to deliver a fast, lightweight mapping solution with small hardware requirements while keeping close compatibility with the Leaflet API.

MapLibre GL JS was trimmed to only the needed features, Leaflet API was rewritten in TypeScript, and paired with client-provided CSS so the library stays lean and maintainable.

This is a highly customized fork of MapLibre GL JS that removes most of its vector rendering features to reduce final package size and adds a Leaflet-like API on top, for ease of transitioning from Leaflet to MapLibre. Additionally, some Leaflet plugins were integrated into this library (see below).

Reading this documentation

This documentation is divided into two parts: the retained original MapLibre API and the new Leaflet API.

Differences from MapLibre and Leaflet

Many parts of the MapLibre API were removed, however what is retained is generally unchanged.

Leaflet API should be mostly similar to Leaflet 2.0 pre-alpha (it was modelled after the development branch of Leaflet in its state from early 2025). However, the entire API was rewritten in TypeScript, including the implementation of many Leaflet classes.

Notable differences from base Leaflet:

  • All code is typed.
  • Classes and functions can now also be imported directly, without using L!
    • But the Leaflet-like API can still be accessed using L, so simpler code built for Leaflet should work as-is with this library.
  • Some details were changed to make the TypeScript transition possible.
    • Some secondary Leaflet functionality was not implemented.
  • The internal implementation of all Leaflet classes has changed - for example, custom Layer types based on old Leaflet will not work.
  • The main Leaflet map class is called LeafletGlMap.
  • The _map member in Layer can be either LeafletGlMap or a LayerGroup. To access the map, use _map.leafletMap.
  • Most factory functions from Leaflet (such as map()) are now unnecessary - you can use a regular constructor instead.
  • Leaflet expect coordinates in the array form to be in the order [lat, lng] while MapLibre expects [lng, lat]. Each of the two APIs expects its order of coordinates. Avoid this problem entirely by passing coordinates as an object { lng: 12, lat: 34 }!
  • A new scheme for ordering layers (both in Leaflet and MapLibre) was added - each layer can have a specified "z-index"-like value, and layers with higher value render on top layer with lower value. This is useful when often adding and removing layers that need to retain a certain order.

Some third-party plugins were integrated into the library and rewritten in TypeScript:

Additionally, several new layer types were implemented, as well as helper classes for tile management:

  • CanvasLayer - A layer that can be used to render content using a 2D canvas context. The rendered image is automatically transferred to a WebGL texture and is placed inside MapLibre's layer stack. It can both render on top and be rendered on top of MapLibre's other WebGL layers.
  • CanvasTileLayer - A layer for rendering tile-based data, where each tile is drawn into a 2D canvas. Based on CanvasLayer.
  • ReferenceCountedCache - A cache for automatic creation, awaiting and deletion of objects that require nontrivial processing to obtain, such as preprocessed tiles.
  • TileCache - a class for managing the visible tile set, which automatically loads needed tiles and deletes unneeded ones.