Build and Development

This page provides an overview of Leaflet's development environment, build system, testing framework, and development workflow. It covers the essential tools, processes, and commands needed to contribute to Leaflet or build it from source.

For detailed information about the CI/CD pipeline and automated workflows, see Build System and CI/CD. For contributing guidelines and code style requirements, see Contributing Guidelines.

Development Environment Setup

Leaflet requires Node.js (version 24 is used in CI) and npm for development. The build system uses modern ES modules and requires no additional global tools beyond Node.js.

Initial Setup

# Clone the repository
git clone https://github.com/Leaflet/Leaflet.git
cd Leaflet

# Install dependencies
npm install

# Build the library
npm run build

Key Dependencies

Dependency	Purpose	Configuration
rollup	JavaScript bundler	build/rollup-config.js1-75
eslint	Code linting	eslint.config.js1-126
karma	Test runner	package.json19-30
mocha + chai	Test framework	package.json17-28
terser	Code minification	package.json10
leafdoc	API documentation	package.json26

Source Code Organization

The Leaflet source code is organized into a modular structure under the src/ directory, with each major subsystem in its own subdirectory.

100%

Module Entry Point

The main entry point src/Leaflet.js1-24 re-exports all public APIs from the subdirectories:

• control/ - UI controls (zoom, attribution, layers)
• core/ - Base classes (Class, Evented, Util)
• dom/ - DOM utilities and event handling
• geometry/ - Geometric primitives (Point, Bounds, Transformation)
• geo/ - Geographic primitives (LatLng, LatLngBounds, CRS)
• layer/ - All layer types (tiles, vectors, markers, etc.)
• map/ - The Map class and handlers

Build Process Overview

Leaflet uses Rollup as its bundler to create multiple output formats from the ES module sources. The build process generates four JavaScript bundles plus CSS and image assets.

Build Configuration

The Rollup configuration build/rollup-config.js1-75 defines:

Input: build/rollup-config.js51

input: './src/Leaflet.js'

Output Formats:

File	Format	Features	Purpose
dist/leaflet-src.js	ESM	Sourcemap, unminified	Development (NPM main export)
dist/leaflet.js	ESM	Minified, sourcemap	Production ESM
dist/leaflet-global-src.js	UMD	Global L, sourcemap	Development (browser)
dist/leaflet-global.js	UMD	Global L, minified	Production (CDN)

Static Assets:

The staticAssetsPlugin build/rollup-config.js16-24 copies these files to dist/:

• leaflet.css
• images/logo.svg
• images/layers.svg
• images/marker-icon.svg
• images/marker-shadow.svg

NPM Scripts

100%

Key Commands:

• npm run build - Build all output bundles package.json54
• npm run watch - Rebuild on file changes package.json55
• npm test - Run tests in Chrome headless package.json52
• npm run coverage - Generate coverage report package.json53
• npm run lint - Check code style package.json56
• npm run lintfix - Auto-fix linting issues package.json57
• npm run docs - Generate API documentation package.json51
• npm run debug - Start local HTTP server package.json50

Testing Framework

Leaflet uses Karma as the test runner with Mocha as the test framework and Chai for assertions. Tests are located in the spec/ directory.

Test Execution Flow

100%

Browser Testing

Tests run in multiple browsers via Karma launchers package.json20-29:

• Chrome / ChromeHeadless (default)
• Firefox / FirefoxHeadless
• FirefoxRetina (Firefox with devicePixelRatio=2)
• SafariNative (macOS only)

Running Tests:

# Default (Chrome headless)
npm test

# Specific browser
npm test -- --browsers Firefox

# With coverage
npm run coverage

# Keep running (watch mode)
npm test -- --no-single-run

Server-Side Rendering Tests

Leaflet validates SSR compatibility in both Node.js and Deno environments .github/workflows/main.yml94-121:

• spec/ssr/ssr_node.js - Node.js SSR test
• spec/ssr/ssr_deno.js - Deno SSR test

Development Workflow

The typical development workflow involves making changes to source files, running the build in watch mode, and testing in a browser.

Interactive Development Loop

100%

Watch Mode Development

For active development, use watch mode CONTRIBUTING.md113-118:

1. Start the build watcher: npm run watch
2. Open a debug page in debug/ directory
3. Edit source files in src/
4. Reload the browser to see changes

The debug pages automatically load dist/leaflet-src.js with sourcemaps, making debugging straightforward.

Git Pre-commit Hook

Leaflet uses Husky to run linting automatically before commits package.json60:

# Configured via husky
npm run lint  # Runs automatically on git commit

To skip the hook (for WIP commits):

git commit -m "WIP" --no-verify

Quality Assurance

Leaflet enforces code quality through multiple automated checks that run both locally and in CI.

Linting Configuration

ESLint enforces code style using eslint.config.js1-126:

Configuration	Purpose
eslint-config-mourner	Base code style
@eslint/css	CSS linting
eslint-plugin-import-x	ES module imports
eslint-plugin-baseline-js	Browser compatibility
@mapbox/eslint-plugin-script-tags	Markdown code blocks

Key Rules:

• Tabs for indentation eslint.config.js43
• Mandatory curly braces eslint.config.js37
• ES module extensions required eslint.config.js41
• Browser baseline: widely available APIs eslint.config.js84-91

Bundle Size Monitoring

Bundlemon .bundlemonrc.json1-24 enforces size limits:

File	Max Size (gzipped)
dist/leaflet.js	40 KB
dist/leaflet.css	3.2 KB

Bundle size checks run in CI .github/workflows/main.yml70-93 and report status on pull requests.

Integrity Hash Generation

The build/integrity.js script build/integrity.js1-38 generates SHA-256 integrity hashes for CDN distribution:

npm run docs  # Generates docs AND updates integrity hashes

This updates docs/_config.yml with hashes for:

• leaflet.js
• leaflet-src.js
• leaflet-global.js
• leaflet-global-src.js
• leaflet.css

Package Distribution

Leaflet is distributed through multiple channels, each with specific file formats.

NPM Package

The package package.json37-44 exports:

{
  "exports": {
    ".": "./dist/leaflet-src.js",
    "./styles.css": "./dist/leaflet.css"
  },
  "type": "module"
}

Included Files: package.json42-48

• dist/ - Built files
• src/ - Source code
• CHANGELOG.md

Installation:

npm install leaflet

Import:

import * as L from 'leaflet';
import 'leaflet/styles.css';

CDN Distribution

The UMD builds (leaflet-global.js and leaflet-global-src.js) are optimized for CDN usage via jsDelivr, with integrity hashes for Subresource Integrity (SRI) validation.

GitHub Releases

CI automatically publishes development snapshots to GitHub Releases .github/workflows/main.yml164-191:

• Tag: dev
• Includes dist/leaflet.zip with all built files

Development Environment Matrix

Leaflet is tested across multiple operating systems and browsers to ensure compatibility.

CI Environment Matrix

OS	Browsers Tested
Ubuntu	Chrome, Firefox, Firefox (Retina)
macOS	Chrome, SafariNative
Windows	Chrome

All platforms use Node.js 24 .github/workflows/main.yml6

Required Tools

Tool	Purpose	Version
Node.js	Build system	24
npm	Package manager	(bundled with Node)
Ruby	Documentation server	See docs/.ruby-version
Chrome/Firefox	Testing	Latest

Related Documentation

• Build System and CI/CD - Detailed CI/CD pipeline, GitHub Actions workflows, automated testing matrix, and release process
• Contributing Guidelines - Code style requirements, PR workflow, branch management, and commit conventions