For many front-end WebGIS engineers, Leaflet is often the first open-source mapping library they encounter when entering the field. Exactly ten years have passed since Leaflet 1.0 was released in September 2016. Over the past decade, the front-end ecosystem has long moved from AMD and global variables to ESM, TypeScript, and modern build tools. Recently, the Leaflet team released version 2.0.0-beta.1, marking the largest modernization refactor in its history. Today I will walk you through what this ten-year-old library has updated and what impact those changes bring.

Modernized Underlying Architecture

The core change in Leaflet 2.0 is that it completely abandons the old prototype inheritance system and rewrites the underlying layer entirely based on standard ES6 classes. Class.extend(), familiar to existing users, officially retires. The new version fully adopts the native ESM specification and achieves full Tree-shaking capability. For a minimal map that only needs a basemap and tiles, the bundled minified size has dropped directly from 38KB to 25.6KB. In addition, the official team has abandoned IE compatibility, and underlying event listening has been fully switched to the modern standard PointerEvents, making the code cleaner.

Strict TypeScript Types

In the past, using Leaflet with TypeScript meant relying only on the community-maintained @types/leaflet, and version updates could easily lead to type mismatches or even declaration conflicts. In version 2.0, the official team builds and distributes accompanying TypeScript type definitions from the source code, so developers no longer need to configure third-party declaration packages. API naming has also undergone a round of flattening adjustments. For example, Control.Zoom has been changed to ZoomControl, TileLayer.WMS to WMSTileLayer, and Icon.Default to DefaultIcon. Every class and event has rigorous type inference, and plugin developers can also more naturally add properties and methods to native classes through module augmentation.

Built-in SVG Icons

In version 1.x, if the static asset path configuration during the front-end build was even slightly off, the Marker would fail to display. This was a historical issue that troubled countless beginners. Leaflet 2.0 finally ends this pain point. The official team has removed separately distributed PNG image assets and upgraded the default marker icon to an inline vector SVG, achieving true out-of-the-box usability. Developers can directly use any CSS color to color the default icon, for example new DefaultIcon({color: 'crimson'}). The new version also adds a rotation parameter and a setRotation() method, natively supporting marker angle rotation without introducing third-party plugins.

Rendering Acceleration and Bug Fixes

At the rendering level, the new version introduces a subpixel precision rendering mechanism, solving the subtle black lines and gaps that occasionally appear between adjacent tiles and polygons at certain zoom levels. The tile seam issue that has plagued the community for years has finally been resolved.

In terms of execution performance, object creation time in the new version has been reduced by about 50%, default icon rendering speed has improved by 25% to 45%, and polygon vector clipping speed has improved by 10% to 55%. It also fixes the stuttering defect where dragging large layers could trigger global reflow rendering, making panning and zooming smoother.

Non-Compatible Changes

However, the major rewrite of the underlying architecture also brings a series of non-compatible changes that require careful handling.

First, the module export mechanism has changed. Version 2.0 removes the default export and no longer supports writing import L from 'leaflet' directly. You must use named imports such as import { TileLayer, Marker } from 'leaflet' or namespace imports such as import * as L from 'leaflet'.

Second, global variables have been decoupled. The default build output no longer mounts window.L to the global scope. If you rely on this feature, you need to explicitly include the separate leaflet-global.js compatibility package.

Third, there is the vast historical plugin ecosystem. A large number of community plugins accumulated over the past decade are deeply bound to Class.extend(). Before mainstream plugins complete their 2.0 adaptation, the risk of hastily upgrading existing large and complex systems is relatively high. For production environments, it is recommended to continue staying on the 1.x stable version.

Conclusion

At a time when 3D digital twins and GPU rendering are popular in the industry, lightweight 2D maps still have irreplaceable lightweight advantages in government and enterprise dashboards, business large screens, and mobile devices. Leaflet 2.0 has completely shed its historical baggage and, while retaining its lightweight characteristics, embraces modern front-end standards, injecting new vitality into this classic old library.

However, we are already in the AI era, and people rarely hand-write front-end code anymore. Is Leaflet's major version refactor a bit late, and does it still have meaning?

References

  1. Leaflet 2.0.0-beta.1 release notes: https://github.com/Leaflet/Leaflet/releases/tag/v2.0.0-beta.1
  2. Leaflet 2.0 official migration guide: https://github.com/Leaflet/Leaflet/blob/main/MIGRATION.md
  3. Leaflet official GitHub repository: https://github.com/Leaflet/Leaflet