Leaflet 2.0 beta: a 40 kB map library that now ships ES module source
GitHub describes it as 🍃 JavaScript library for mobile-friendly interactive maps 🇺🇦. The repository metadata lists JavaScript as its primary language. The metadata lists the BSD-2-Clause license. This article stays within the project description and details documented in the GitHub repository README.
At a glance
- What is it?
- Leaflet is the BSD-2-Clause JavaScript library for interactive web maps. Its main branch now carries version 2.0.0-beta.1, which changes how the package is consumed and puts an upgrade decision in front of every existing user.
- Who is it for?
- Leaflet fits developers who want a small, plain JavaScript map library they can extend with plugins and who are comfortable with ES modules. Teams on an existing 1.x setup, or anyone who needs a React, Next.js or R binding, should not treat the 2.0 beta on main as a drop-in update: read MIGRATION.md, check that every plugin you depend on works with 2.0, and confirm on the install page which build is the current stable one before choosing a version.
- Can I use it commercially?
- Yes. BSD-2-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Leaflet/Leaflet45,930 ★ · +451
| Repository | 2026-08-13 | 2026-11-15 |
|---|---|---|
| Leaflet/Leaflet | 45.5k | 45.9k |
451 Stars in the last 94 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
A 40 kB core that leaves the rest to plugins
Leaflet's size budget is about 40 kB of gzipped JavaScript plus 2.4 kB of gzipped CSS. The project's own position is that this core covers the mapping features most developers need, and that anything beyond it comes from the plugin catalogue at leafletjs.com/plugins.html. The repository keeps a PLUGIN-GUIDE.md at the top level for people writing those extensions.
The consequence of that split is practical. When a feature you want is not in the core, you are choosing a third party package with its own maintainer and its own release pace, not a part of Leaflet. Before you commit to a plugin, check whether it has been updated for the version of Leaflet you plan to run, because the core and its plugins move independently. The API reference at leafletjs.com/reference.html is where to confirm what the core itself provides.
The 2.0 line on main is still a beta
The package.json on the default branch, main, declares version 2.0.0-beta.1, and a release with that tag was published on 2026-11-02. Before it came v2.0.0-alpha.1 on 2025-08-16 and a rolling dev snapshot dated 2025-09-17. So anyone who installs from the repository head, or picks the newest tag, is on prerelease code.
The repository carries a MIGRATION.md file, and the npm package includes it in its published files next to CHANGELOG.md. That file is the place to learn what changed for 2.0; this guide cannot list those changes for you. If you run a production map on an older release, do not bump to the beta without reading MIGRATION.md and running your own tests, and check the install page for which version the project currently presents as the main download.
The npm entry point is ES module source, not a bundle
The package is published as leaflet and its package.json sets "type": "module". The exports map points the main entry straight at the source tree rather than at a prebuilt file:
"exports": {
".": {
"types": "./dist/types/index.d.ts",
"default": "./src/Leaflet.js"
},Type definitions come from dist/types/index.d.ts, so TypeScript users get types without a separate package. The cost is on the consuming side: whatever loads Leaflet from npm has to understand ES modules, because the default export condition resolves to src/Leaflet.js. A build pipeline or script tag setup that only handles older module formats will need changes before it can use 2.0 from npm. The README badge also points to esm.run/leaflet for loading the module from a CDN.
The stylesheet ships as its own export
CSS is not pulled in by importing the JavaScript entry. The package exposes it through two subpaths that resolve to the same file:
"./dist/leaflet.css": "./dist/leaflet.css",
"./styles.css": "./dist/leaflet.css"The "style" field also names dist/leaflet.css, and "sideEffects" is set to ["*.css"]. That last setting tells bundlers not to drop CSS imports during tree shaking, while every JavaScript module stays eligible for removal when unused. In practice this means your application code has to import the stylesheet explicitly, using either leaflet/dist/leaflet.css or leaflet/styles.css. If you forget, the JavaScript still loads but the map is rendered without the rules shipped in those 2.4 kB of CSS.
React, Next.js and R bindings are not in this repository
A lot of people arrive at Leaflet through a framework: searches for React Leaflet, Leaflet with Next.js, Leaflet in R, or Leaflet maps inside Obsidian are common. None of those integrations live in this repository. Its top level holds src/, spec/, build/, debug/ and docs/, plus the guides for contributors, plugins and migration, and the package.json lists no framework dependencies.
For readers that means two things. First, a wrapper library is a separate project with its own release schedule, and it may not support the 2.0 beta yet. Second, answers about server side rendering, component lifecycles or offline tile storage have to come from that wrapper or from a plugin, not from Leaflet itself. Pick the wrapper first, then pin the Leaflet version that wrapper declares it supports.
Browser tests run through Vitest and Playwright
The development toolchain is visible in package.json. Builds go through rolldown with a config at build/rolldown-config.js, and typescript 7.1.0-beta sits in the dev dependencies alongside a separate build:types step. Documentation is generated with leafdoc. Tests use Vitest with the @vitest/browser and @vitest/browser-playwright packages, so the suite runs in real browsers instead of a simulated DOM. Interaction tests lean on sinon and ui-event-simulator.
The relevant scripts are short:
"debug": "node build/serve.js",
"test": "vitest run",
"test:ui": "vitest --ui --browser.headless=false",
"coverage": "vitest run --coverage",The test:ui script turns headless mode off, so a contributor can watch the suite drive a visible browser while debugging a failing interaction. Because the tests depend on Playwright, a plain Node setup is not enough to run them. CONTRIBUTING.md is the starting point for anyone sending patches.
Built in Kyiv, with a statement at the top of its README
Volodymyr Agafonkin, a Ukrainian citizen living in Kyiv, created Leaflet in 2010. The README opens with a statement from the maintainers about Russia's full scale invasion of Ukraine before it gets to any technical content. It names concrete uses of the library: documenting war crimes through the Bellingcat map, tracking the front line on DeepStateMap, and finding humanitarian aid. The maintainers ask readers to donate to Come Back Alive or another charity listed on StandWithUkraine.
On activity, the repository is not archived and its last push was on 2026-11-02, the same day the 2.0.0-beta.1 tag was published. The project is licensed under BSD-2-Clause, and it includes a CITATION.cff file for anyone who needs to cite it.
Editorial conclusion
Leaflet fits developers who want a small, plain JavaScript map library they can extend with plugins and who are comfortable with ES modules. Teams on an existing 1.x setup, or anyone who needs a React, Next.js or R binding, should not treat the 2.0 beta on main as a drop-in update: read MIGRATION.md, check that every plugin you depend on works with 2.0, and confirm on the install page which build is the current stable one before choosing a version.
Frequently asked questions
What is Leaflet used for?
Leaflet is a JavaScript library for building interactive, mobile-friendly maps on the web. Its maintainers point to maps that document war crimes in Ukraine, track the front line and help people find humanitarian aid.
How do I install Leaflet?
The npm package is named leaflet, and the project's install page at leafletjs.com/install.html lists the downloads, including the built main version. The 2.0 line is loaded as an ES module, and esm.run/leaflet serves it from a CDN.
How do I use Leaflet.js?
Start with the docs and tutorials on leafletjs.com and the API reference at leafletjs.com/reference.html. When installing from npm, import the JavaScript entry and the stylesheet separately, from leaflet/dist/leaflet.css or leaflet/styles.css.
Official sources
Where developers are discussing it
Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 1 in the last 30 days; newest first.
- Leaflet 2.0 BetaHacker News · Nov 2, 2026 · 3 points · 0 comments
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/leaflet-leaflet)Star history chart for your README
[](https://hysenlabs.com/projects/leaflet-leaflet)Was this useful?