Установка через npm

Библиотека распространяется как полноценный npm-пакет и подключается стандартным способом через менеджер зависимостей. Основная команда установки:

npm install leaflet

или при использовании yarn:

yarn add leaflet

или pnpm:

pnpm add leaflet

После установки пакет попадает в node_modules, а его версии фиксируются в package.json, что обеспечивает воспроизводимость сборки и корректную работу в командных проектах.

Подключение модуля в современных сборщиках

Leaflet поддерживает ES Modules, поэтому импорт выполняется напрямую из пакета без обращения к глобальным переменным.

import L from 'leaflet';

В этом случае вся функциональность библиотеки доступна через объект L, который является основным пространством имён Leaflet.

При использовании TypeScript дополнительные типы подтягиваются автоматически, поскольку пакет содержит встроенные определения:

import * as L from 'leaflet';

const map: L.Map = L.map('map');

Подключение CSS-стилей

Одной из обязательных частей интеграции является подключение стилей. Без CSS карта будет отображаться некорректно: элементы управления и тайлы потеряют оформление.

В сборщиках (Vite, Webpack, Rollup) стили импортируются напрямую:

import 'leaflet/dist/leaflet.css';

Этот импорт позволяет системе сборки включить стили в итоговый бандл без необходимости подключать отдельные CSS-файлы вручную.

Инициализация карты после npm-установки

После подключения библиотеки и стилей создаётся базовый объект карты.

import L from 'leaflet';
import 'leaflet/dist/leaflet.css';

const map = L.map('map').setView([51.505, -0.09], 13);

Контейнер map должен существовать в DOM:

<div id="map"></div>

Обязательное условие — наличие размеров у контейнера:

#map {
  height: 500px;
}

Без заданной высоты карта не отобразится, поскольку элемент не имеет визуального пространства.

Добавление тайлового слоя

Leaflet не содержит встроенных картографических данных, поэтому используется внешний тайловый сервис. Пример подключения OpenStreetMap:

L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
  attribution: '&copy; OpenStreetMap contributors'
}).addTo(map);

Этот слой является базовым визуальным представлением карты и необходим для большинства сценариев использования.

Особенности работы с Webpack и Vite

При использовании сборщиков могут возникать нюансы, связанные с путями к ресурсам и обработкой статических файлов.

Проблема с иконками маркеров

Leaflet по умолчанию использует изображения маркеров, которые в npm-версии могут не подтягиваться автоматически. Это связано с тем, что пути к PNG-файлам не всегда корректно резолвятся сборщиком.

Типичная проблема: маркеры не отображаются, вместо них пустые блоки.

Решение заключается в явной настройке путей к иконкам:

import L from 'leaflet';
import iconUrl from 'leaflet/dist/images/marker-icon.png';
import iconShadow from 'leaflet/dist/images/marker-shadow.png';

delete L.Icon.Default.prototype._getIconUrl;

L.Icon.Default.mergeOptions({
  iconUrl,
  shadowUrl: iconShadow
});

В некоторых конфигурациях Webpack требуется дополнительная настройка загрузчиков изображений (file-loader или asset modules), однако современные версии сборщиков (Vite, Webpack 5) обычно обрабатывают это автоматически.

Использование CommonJS (устаревший способ)

В старых проектах возможен импорт через require, однако он не рекомендуется при использовании современных инструментов сборки.

const L = require('leaflet');

Такой подход ограничивает tree-shaking и ухудшает оптимизацию итогового бандла.

Tree-shaking и влияние на размер бандла

Leaflet частично поддерживает модульную структуру, но основное пространство имён остаётся монолитным. Это означает, что импорт L обычно подтягивает значительную часть функциональности.

В проектах, где важен минимальный размер бандла, используется:

  • динамический импорт модулей
  • разделение кода (code splitting)
  • ленивое создание карты при необходимости

Пример динамической загрузки:

async function loadMap() {
  const L = await import('leaflet');

  const map = L.map('map').setView([51.505, -0.09], 13);
}

Версионирование пакета

Leaflet использует семантическое версионирование. Обновление версии может влиять на API и поведение отдельных компонентов, особенно при переходе между мажорными релизами.

Проверка установленной версии:

npm list leaflet

Или через package.json:

{
  "dependencies": {
    "leaflet": "^1.9.4"
  }
}

Символ ^ позволяет автоматически обновлять минорные версии, сохраняя совместимость API.

Подключение в проектах без сборщика

Хотя npm-установка чаще используется в связке с bundler’ами, возможна работа и без них через инструменты вроде Parcel или при ручной настройке ESM в браузере.

Однако в таком случае требуется дополнительная конфигурация путей к модулям, поскольку браузер не умеет разрешать bare imports (leaflet без URL).

Совместимость с TypeScript

Leaflet предоставляет встроенные типы, что позволяет использовать строгую типизацию без дополнительных пакетов @types/leaflet.

Пример типизированного объекта:

import L from 'leaflet';

const map: L.Map = L.map('map');

const marker: L.Marker = L.marker([51.5, -0.09]);
marker.addTo(map);

Типизация охватывает основные сущности: Map, Marker, TileLayer, Popup, GeoJSON и другие.

Частые ошибки при установке через npm

Типичные проблемы при интеграции:

  • отсутствие подключения CSS-файла
  • неправильный путь к иконкам маркеров
  • создание карты до рендера DOM-элемента
  • отсутствие фиксированной высоты контейнера
  • конфликт версий сборщика и ESM-модуля

Каждая из этих ошибок приводит к визуально пустой или некорректно отображаемой карте, хотя сама библиотека при этом может быть подключена правильно.

Структура установленного пакета

После установки в node_modules/leaflet присутствуют основные компоненты:

  • dist/ — собранные UMD и ESM версии
  • src/ — исходные модули библиотеки
  • dist/images/ — иконки и служебные изображения
  • package.json — описание экспортов и точек входа

Основной entry-point определяется автоматически сборщиком через поле module или exports.

Импорт отдельных частей библиотеки

Хотя Leaflet чаще используется как единый объект L, в некоторых конфигурациях возможен импорт отдельных модулей (в зависимости от сборки):

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

Такой подход может улучшить читаемость и частично оптимизировать бандл, но требует корректной поддержки tree-shaking со стороны сборщика.

Поведение в продакшн-сборке

При сборке для production важно учитывать:

  • минификацию кода Leaflet
  • корректную обработку статических ресурсов
  • кеширование тайловых запросов
  • CSP-политику при загрузке внешних картографических серверов

Библиотека не накладывает ограничений на окружение, но полностью зависит от конфигурации проекта, в который она интегрируется.

Оглавление