leaflet

library0.0.3jsnpmunverified

Leaflet is a lightweight, open-source JavaScript library designed for creating mobile-friendly interactive maps. It focuses on performance, usability, and extensibility, providing a core set of features like layers, markers, popups, and controls, while supporting a rich ecosystem of plugins for advanced functionality. The current stable major version is 1.x, with `1.9.4` being the latest bugfix release, which is now in maintenance mode, receiving only critical bugfixes. Development has shifted significantly towards the upcoming 2.0 release, currently in alpha, which modernizes the codebase by dropping Internet Explorer support, removing legacy methods, and fully embracing ES Modules. Its simple API and strong community support make it a popular choice for web mapping applications, particularly where performance and bundle size are critical.

web-framework

npm install leaflet

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LEAFLET

leaflet

web-frameworkjavascriptv0.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

L (global object)

✓ import 'leaflet'; // Makes L globally available (v1.x) // or via script tag: <script src="leaflet.js"></script>

✗ import { L } from 'leaflet';

In Leaflet 1.x, the library typically exposes a global `L` object. Direct named imports for `L` are not supported. For bundlers, `import 'leaflet'` makes `L` available globally or through `window.L`.

Named exports (Map, tileLayer, marker)

✓ import { Map, tileLayer, marker } from 'leaflet';

✗ const L = require('leaflet'); L.map(...);

Leaflet 2.x is fully ESM, meaning core components are named exports. The global `L` is no longer part of the core package but is available in the bundled `leaflet-global.js`.

ESM explicit path (v1.9.2+)

✓ import 'leaflet/dist/leaflet-src.esm.js';

✗ import 'leaflet';

Due to compatibility issues with plugins, the default ESM entrypoint was removed from the `leaflet` package in `v1.9.2`. Users wanting ESM in 1.x must explicitly import this path.

TypeScript types

✓ import * as L from 'leaflet'; // Ensure @types/leaflet is installed: npm install --save-dev @types/leaflet

For TypeScript with Leaflet 1.x, importing all as `L` is a common pattern when using bundlers, alongside `@types/leaflet` for type definitions.

This quickstart demonstrates how to initialize a basic Leaflet map, add an OpenStreetMap tile layer, and place a marker with a popup. It also addresses the common issue of missing marker icons when using bundlers.

import 'leaflet/dist/leaflet.css'; // Essential for Leaflet styles // For TypeScript with bundlers and Leaflet 1.x, `import * as L from 'leaflet';` is common. // For native browser usage with script tags, `L` is globally available. import * as L from 'leaflet'; // A common issue in bundlers is that Leaflet's default marker icons aren't correctly resolved. // We override L.Icon.Default to point to known URLs, preventing missing marker images. L.Icon.Default.mergeOptions({ iconRetinaUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon-2x.png', iconUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-icon.png', shadowUrl: 'https://unpkg.com/leaflet@1.9.4/dist/images/marker-shadow.png' }); document.addEventListener('DOMContentLoaded', () => { // Ensure a map div exists let mapDiv = document.getElementById('map'); if (!mapDiv) { mapDiv = document.createElement('div'); mapDiv.id = 'map'; mapDiv.style.height = '400px'; mapDiv.style.width = '100%'; document.body.appendChild(mapDiv); } // Initialize the map on the 'map' div with a given view and zoom level const map = L.map('map').setView([51.505, -0.09], 13); // Add an OpenStreetMap tile layer to the map L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors' }).addTo(map); // Add a marker to the map at a specific coordinate L.marker([51.5, -0.09]) .addTo(map) .bindPopup('A sample marker in London!') .openPopup(); });

Debug

Known issues

breakingLeaflet v2.0 introduces a full conversion to ES Modules, fundamentally changing how the library is imported. The global `L` object is no longer provided by the core package. Legacy CommonJS `require` is also no longer supported for the core.

fix

Migrate imports to use named ES Module syntax (e.g., `import { Map, tileLayer } from 'leaflet';`). For users relying on the global `L`, consider using the bundled `leaflet-global.js` or adapting to named imports.

affects: >=2.0.0-alpha

breakingLeaflet v2.0 has dropped support for Internet Explorer and removed many legacy methods and polyfills, adopting modern web standards like Pointer Events. This may cause issues in older browser environments or with plugins relying on deprecated APIs.

fix

Ensure your target browser environment meets modern standards. Review custom plugins and code for reliance on deprecated Leaflet 1.x APIs or IE-specific logic.

affects: >=2.0.0-alpha

gotchaAs of v1.9.0, the Leaflet 1.x branch has entered maintenance mode, meaning future releases will be reserved primarily for critical bugfixes. New features and significant development are focused on the 2.x branch.

fix

While 1.x remains stable, plan for eventual migration to Leaflet 2.x to benefit from ongoing development, modernizations, and new features.

affects: >=1.9.0

gotchaThe default ESM entrypoint was temporarily removed from the main package in v1.9.2 due to compatibility issues with plugins. Importing `leaflet` via ESM might not work as expected in some bundlers.

fix

If you need an ESM entrypoint in 1.x, explicitly import `leaflet/dist/leaflet-src.esm.js`. For most users with bundlers, `import 'leaflet'` or `require('leaflet')` might still resolve to the CJS or UMD bundle.

affects: >=1.9.2 <2.0.0

gotchaWhen using bundlers (like Webpack, Vite) with Leaflet 1.x, the default marker icons often fail to load because their paths are relative and not correctly handled by the bundler's asset pipeline.

fix

Manually set `L.Icon.Default.mergeOptions` to point to absolute URLs for the icon images (e.g., from unpkg.com) or configure your bundler to copy and correctly resolve the images from `node_modules/leaflet/dist/images`.

affects: >=1.0.0 <2.0.0

Errors

Common errors & fixes

ReferenceError: L is not defined

The Leaflet library was not properly loaded or imported, or you are trying to use `L` in a Leaflet 2.x ESM-only environment without the global bundle.

fix

For Leaflet 1.x, ensure `leaflet.js` is loaded via a `<script>` tag or `import 'leaflet'` is used in a bundler setup. For Leaflet 2.x, use named imports like `import { Map } from 'leaflet';` or ensure you are loading the `leaflet-global.js` bundle if you require the global `L`.

TypeError: Cannot read properties of undefined (reading 'mergeOptions') OR Failed to load resource: the server responded with a status of 404 (Not Found) for marker images.

Leaflet's default marker icons cannot be found by the browser, usually because a bundler hasn't correctly resolved the relative image paths from `node_modules`.

fix

Override Leaflet's default icon paths to point to absolute URLs (e.g., `L.Icon.Default.mergeOptions({ iconRetinaUrl: 'https://...', iconUrl: 'https://...', shadowUrl: 'https://...' });`) or configure your bundler to copy `node_modules/leaflet/dist/images` to your public asset folder.

Cannot find module 'leaflet' OR Attempted import error: 'Map' is not exported from 'leaflet'.

This can occur in Leaflet 1.x when attempting named imports that are not available, or in 2.x if the environment isn't correctly resolving ES Modules, or trying to use new ESM imports in a 1.x environment.

fix

For Leaflet 1.x, rely on the global `L` object or `import * as L from 'leaflet';` in TypeScript. For Leaflet 2.x, ensure your build setup supports ES Modules and use named imports like `import { Map, tileLayer } from 'leaflet';`. If on Leaflet `v1.9.2` or later and explicitly want ESM, import `leaflet/dist/leaflet-src.esm.js`.

Upgrade

Version history

0.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Leaflet/Leaflet ↗

packagehttps://www.npmjs.com/package/leaflet ↗

homepagehttps://leafletjs.com ↗