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

Библиотека Leaflet подключается как обычная npm-зависимость и полностью совместима с современными сборщиками JavaScript-проектов. Yarn используется как менеджер пакетов, обеспечивающий предсказуемую установку зависимостей и быстрый процесс работы с node_modules.

Перед установкой требуется наличие окружения Node.js, поскольку Yarn работает поверх npm-регистра и использует его инфраструктуру.

Инициализация проекта

Создание нового проекта выполняется через стандартную инициализацию package.json:

yarn init -y

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

При необходимости структура проекта может быть расширена под конкретную архитектуру фронтенд-приложения:

/project
  /src
  /dist
  package.json

Установка Leaflet

Основной пакет библиотеки устанавливается из npm-реестра:

yarn add leaflet

После выполнения команды Yarn:

  • загружает пакет Leaflet в node_modules
  • фиксирует версию в package.json
  • обновляет yarn.lock для детерминированной сборки

В package.json появляется зависимость:

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

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

Установка типов для TypeScript (при необходимости)

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

yarn add -D @types/leaflet

Пакет устанавливается как dev-dependency, поскольку используется только на этапе компиляции.

В результате появляется поддержка:

  • строгой типизации объектов карты
  • автодополнения методов API
  • проверки параметров слоёв, маркеров и событий

Подключение Leaflet в проект

После установки библиотеку можно импортировать в модульной системе ES:

import L from 'leaflet';

Для проектов без сборщика (например, при использовании Vite, Webpack или аналогов) Leaflet корректно работает в ESM-режиме.

Также возможен импорт CSS, необходимого для корректного отображения карты:

import 'leaflet/dist/leaflet.css';

CSS содержит:

  • стили контейнера карты
  • оформление контролов масштаба
  • стили маркеров и pop-up элементов

Отсутствие этого файла приводит к визуально «сломанной» карте, даже если логика работает корректно.

Использование в сборщиках (Vite, Webpack)

При интеграции через Vite установка через Yarn автоматически учитывается системой модулей:

yarn add leaflet

Далее импорт выполняется напрямую:

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

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

В Webpack дополнительно может потребоваться настройка обработки CSS:

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      }
    ]
  }
};

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

Корректная установка подтверждается фактом наличия пакета в node_modules и отсутствием ошибок при импорте:

console.log(L.version);

Вывод версии библиотеки подтверждает, что модуль успешно подключен и доступен в runtime.

Частые особенности Yarn-установки Leaflet

Структура зависимостей Leaflet минимальна, поэтому установка проходит без дополнительных peer-dependencies.

Однако в проектах с жесткой политикой сборки могут встречаться следующие особенности:

  • необходимость ручного добавления CSS
  • конфликты с tree-shaking при неправильной настройке bundler
  • необходимость фиксации версии при использовании legacy-кода

Использование в монорепозиториях

В Yarn Workspaces Leaflet устанавливается на уровне корневого пакета:

yarn workspace frontend add leaflet

или глобально для всех пакетов:

yarn add leaflet -W

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

Подключение ассетов Leaflet

Leaflet использует дополнительные изображения для маркеров и теней. При сборке через Yarn и современные bundler-ы может потребоваться корректная настройка путей:

import markerIcon from 'leaflet/dist/images/marker-icon.png';
import markerShadow from 'leaflet/dist/images/marker-shadow.png';

В некоторых конфигурациях Webpack требуется явное указание loader’ов для изображений, чтобы избежать ошибок 404 при рендеринге маркеров.

Проверка зависимостей проекта

Контроль установленной версии выполняется через Yarn:

yarn list --pattern leaflet

Команда показывает текущую установленную версию и путь до пакета в дереве зависимостей, что важно при диагностике конфликтов версий в сложных фронтенд-проектах.

Оглавление