Сборка из исходников

Исходный код библиотеки размещается в репозитории и содержит полный набор модулей, тестов, конфигураций сборки и вспомогательных инструментов. Для работы со сборкой используется стандартный стек Node.js.

Клонирование репозитория:

git clone https://github.com/Leaflet/Leaflet.git
cd Leaflet

Структура проекта после загрузки включает ключевые директории:

  • src/ — исходные модули библиотеки
  • dist/ — готовые собранные файлы
  • spec/ — тесты
  • build/ — конфигурации сборки
  • docs/ — документация
  • src/layer/, src/map/, src/control/ — основные функциональные блоки

Установка зависимостей

Сборка Leaflet требует установленной среды Node.js и пакетного менеджера npm.

npm install

В процессе установки подтягиваются зависимости для сборки, тестирования и транспиляции кода.

Основные категории зависимостей:

  • инструменты сборки (Rollup, Babel)
  • инструменты тестирования (Mocha, Chai)
  • линтеры и форматирование кода (ESLint)
  • утилиты для разработки

Архитектура исходного кода

Исходный код Leaflet построен на модульной архитектуре. Каждый функциональный блок реализован в отдельном файле:

  • Map — управление картой, слоями, событиями
  • TileLayer — работа с тайловыми слоями
  • Marker — маркеры на карте
  • Popup — всплывающие окна
  • Control — элементы управления интерфейсом
  • GeoJSON — работа с геоданными

Модули объединяются через систему сборки, а не через стандартные ES6 import/export в рантайме, что позволяет поддерживать совместимость с широким спектром браузеров.

Система сборки

Сборка Leaflet основана на Node.js-скриптах и инструменте Rollup. Основная логика сборки описана в package.json.

Основные команды:

npm run build

Эта команда выполняет полный цикл сборки:

  1. очистка старых билдов
  2. транспиляция исходников
  3. объединение модулей
  4. генерация финальных файлов в dist/

Выходные артефакты сборки

После выполнения сборки создаются несколько вариантов библиотеки:

  • dist/leaflet-src.js — собранный, но не минифицированный код
  • dist/leaflet.js — минифицированная версия для продакшена
  • dist/leaflet.css — стили библиотеки
  • dist/images/ — графические ресурсы

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

Режим разработки

Для работы с изменениями исходного кода используется режим наблюдения:

npm run watch

В этом режиме:

  • отслеживаются изменения в src/
  • автоматически пересобирается dist/leaflet-src.js
  • ускоряется цикл разработки без ручного запуска сборки

Использование Rollup в сборке

Rollup применяется для объединения модулей в единый файл. Конфигурация определяет входную точку и набор плагинов.

Ключевые особенности конфигурации:

  • входной файл: src/Leaflet.js
  • поддержка CommonJS и ES модулей
  • транспиляция через Babel
  • объединение в IIFE формат для браузера

Упрощённая логика конфигурации:

export default {
  input: 'src/Leaflet.js',
  output: {
    file: 'dist/leaflet-src.js',
    format: 'iife'
  },
  plugins: [
    resolve(),
    commonjs(),
    babel()
  ]
};

Транспиляция кода

Исходный код Leaflet может содержать современные возможности JavaScript, которые преобразуются для поддержки старых браузеров.

Babel выполняет:

  • преобразование ES6+ синтаксиса
  • замена модулей
  • полифиллинг при необходимости

Настройки задаются в конфигурации Babel:

{
  "presets": ["@babel/preset-env"]
}

Минификация

Минификация выполняется в процессе сборки production-версии.

Основные задачи:

  • удаление пробелов и комментариев
  • сокращение имён переменных
  • оптимизация выражений

Результат — файл leaflet.js, оптимизированный для загрузки в браузере.

Подключение исходной версии

Собранный исходный файл используется для отладки и разработки:

<link rel="stylesheet" href="dist/leaflet.css">
<script src="dist/leaflet-src.js"></script>

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

Тестирование сборки

Leaflet включает набор автоматических тестов, проверяющих корректность работы основных компонентов.

Запуск тестов:

npm test

Тестовая система основана на Mocha и Chai.

Проверяются:

  • инициализация карты
  • работа слоёв
  • обработка событий
  • корректность геометрических операций

Структура тестов

Тесты расположены в каталоге spec/ и повторяют структуру src/:

  • spec/map/
  • spec/layer/
  • spec/control/

Каждый тестовый файл соответствует конкретному модулю и проверяет его поведение в изолированной среде.

Сборка CSS и ресурсов

Помимо JavaScript, сборочный процесс включает обработку стилей.

Файл leaflet.css формируется из исходных CSS-частей, содержащихся в src/.

Графические ресурсы копируются в dist/images/ без изменений.

Локальная публикация сборки

После выполнения сборки содержимое dist/ может использоваться как самостоятельная библиотека.

Типичная структура подключения:

dist/
  leaflet.js
  leaflet-src.js
  leaflet.css
  images/

Подобная организация обеспечивает независимость от исходного репозитория.

Настройка пользовательской сборки

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

Примеры возможных изменений:

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

Настройка осуществляется через изменение входных модулей в Rollup-конфигурации.

Работа с модульной структурой

Каждый модуль Leaflet имеет чётко определённые зависимости. Пример:

  • Map зависит от Evented
  • TileLayer зависит от GridLayer
  • Popup зависит от DivOverlay

Связи реализуются через внутреннюю систему классов библиотеки, а не через внешние импортируемые пакеты.

Поддержка браузеров

Собранная версия ориентирована на максимальную совместимость. В процессе сборки учитываются ограничения:

  • отсутствие современных ES-модулей в runtime
  • необходимость поддержки старых версий браузеров
  • использование UMD/IIFE формата

Отладка сборки

Для анализа итогового файла используются:

  • source maps (при включении)
  • логирование сборки
  • временные промежуточные файлы

Source maps позволяют сопоставлять минифицированный код с исходными модулями src/.

Интеграция в сторонние сборщики

Собранный код Leaflet может быть встроен в современные системы сборки приложений:

  • Webpack
  • Vite
  • Rollup

В таких случаях чаще используется пакетная версия через npm:

npm install leaflet

Однако при работе с исходниками применяется локальная сборка из репозитория.

Результат сборочного процесса

Сборка формирует полностью автономный набор файлов, включающий:

  • ядро библиотеки
  • стили
  • ресурсы
  • отладочную и production версии

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

Оглавление