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

Установка основной библиотеки

Библиотека MapLibre GL JS устанавливается как стандартный npm-пакет и полностью поддерживается пакетным менеджером Yarn. Основной пакет содержит движок рендеринга векторных тайлов, работу со стилями Mapbox Style Specification, управление слоями и источниками данных.

Команда установки:

yarn add maplibre-gl

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

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

После установки в node_modules/maplibre-gl содержатся ключевые компоненты:

  • ядро WebGL-рендерера
  • обработка стилей (Style Specification)
  • менеджер источников данных (sources)
  • система слоёв (layers)
  • утилиты работы с координатами и проекциями
  • встроенные контролы (zoom, attribution)

Файл входа пакета определяется через поле module или main, в зависимости от сборщика.

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

MapLibre GL JS требует подключения базового CSS-файла, без которого карта будет отображаться некорректно (отсутствие позиционирования контролов, некорректные размеры canvas).

Импорт в модульной системе:

import 'maplibre-gl/dist/maplibre-gl.css';

При использовании Yarn и сборщиков (Vite, Webpack, Rollup) CSS автоматически обрабатывается соответствующим loader’ом или встроенной поддержкой.

Импорт библиотеки в проект

После установки пакет подключается стандартным ES-модулем:

import maplibregl from 'maplibre-gl';

Инициализация объекта карты:

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [30.3, 59.9],
  zoom: 10
});

Типизация и TypeScript

Пакет содержит встроенные TypeScript-типы, поэтому дополнительная установка @types/maplibre-gl не требуется в большинстве версий.

Пример типизированной инициализации:

import maplibregl from 'maplibre-gl';

const map: maplibregl.Map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [30.3, 59.9],
  zoom: 10
});

Типы включают:

  • Map
  • MapOptions
  • GeoJSONSource
  • Layer
  • StyleSpecification

Установка через Yarn в монорепозиториях

В монорепозиториях Yarn Workspaces пакет добавляется в конкретный workspace:

yarn workspace frontend add maplibre-gl

или через корневую установку с указанием workspace-пакета.

Важно учитывать единый lock-файл yarn.lock, который фиксирует версию WebGL-библиотеки во всех пакетах монорепозитория.

Совместимость с Yarn Berry (v2+)

При использовании Yarn Plug’n’Play (PnP) отсутствует node_modules как физическая директория. MapLibre GL JS корректно работает в PnP-режиме при условии поддержки сборщика:

  • Vite с PnP-плагином
  • Webpack 5 с PnP-resolver
  • ESBuild (через совместимые плагины)

В некоторых конфигурациях требуется явное разрешение на использование зависимости:

packageExtensions:
  maplibre-gl@*:
    dependencies:
      tslib: "*"

Подключение в Vite-проектах

Vite автоматически обрабатывает ES-модули MapLibre GL JS без дополнительной конфигурации.

Пример использования:

import 'maplibre-gl/dist/maplibre-gl.css';
import maplibregl from 'maplibre-gl';

const map = new maplibregl.Map({
  container: document.getElementById('map'),
  style: 'https://demotiles.maplibre.org/style.json'
});

При необходимости можно оптимизировать сборку через optimizeDeps:

export default {
  optimizeDeps: {
    include: ['maplibre-gl']
  }
};

Подключение в Webpack

При использовании Webpack требуется корректная обработка CSS и возможная настройка alias для совместимости с ESM.

Установка loader’ов:

yarn add css-loader style-loader --dev

Конфигурация:

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

Работа с версиями

MapLibre GL JS активно развивается, поэтому фиксирование версии важно для стабильности:

yarn add maplibre-gl@^3.0.0

В package.json:

{
  "dependencies": {
    "maplibre-gl": "^3.0.0"
  }
}

Изменения между мажорными версиями могут затрагивать:

  • API источников данных
  • поведение рендеринга символов
  • поддержку определённых форматов стилей
  • оптимизации WebGL pipeline

Подключение локальных стилей и ресурсов

При использовании кастомных стилей JSON рекомендуется хранить их локально:

import style from './style.json';

const map = new maplibregl.Map({
  container: 'map',
  style
});

Yarn и сборщик обеспечивают загрузку JSON как модуля при соответствующей конфигурации.

Частые проблемы при установке

Конфликты зависимостей

Некоторые проекты могут содержать старые версии gl-matrix или earcut. Yarn автоматически дедуплицирует зависимости, но в редких случаях требуется принудительное обновление:

yarn dedupe

Ошибки CSS отсутствия

При отсутствии импорта CSS карта отображается без интерфейсных элементов. Решение:

import 'maplibre-gl/dist/maplibre-gl.css';

Ошибки сборки WebGL

В средах без GPU-ускорения или с отключённым WebGL возможны ошибки инициализации контекста. Это не связано с Yarn, но проявляется на этапе запуска после установки.

Использование с дополнительными плагинами

После установки через Yarn часто подключаются расширения:

  • контролы масштаба и компаса
  • геокодинг
  • кластеризация GeoJSON
  • 3D terrain rendering

Пример установки плагина:

yarn add @maplibre/maplibre-gl-geocoder

И подключение:

import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';
Оглавление