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

Библиотека MapLibre GL JS распространяется как npm-пакет и подключается в современных JavaScript-проектах через стандартную систему модулей. Основной пакет — maplibre-gl, содержащий ядро рендеринга карт на WebGL, систему слоёв, источников данных и API управления картой.

Установка выполняется через любой пакетный менеджер, совместимый с npm-экосистемой.

Установка пакета

Через npm:

npm install maplibre-gl

Через yarn:

yarn add maplibre-gl

Через pnpm:

pnpm add maplibre-gl

После установки пакет становится доступен в node_modules, а его модули могут быть импортированы в коде приложения.

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

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

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

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

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

CSS-файл содержит:

  • стили контейнера карты
  • оформление контролов масштабирования и навигации
  • стили popups и markers
  • базовую структуру UI элементов

Минимальная инициализация карты

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

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

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

Параметры:

  • container — DOM-элемент или его идентификатор
  • style — URL или объект стиля MapLibre Style Specification
  • center — начальные координаты [longitude, latitude]
  • zoom — начальный масштаб

Подключение в HTML-структуре

Контейнер карты должен существовать в DOM до инициализации:

<div id="map" style="width: 100%; height: 100vh;"></div>

Критически важно наличие заданной высоты, иначе WebGL-контекст не отобразит карту.

Использование с современными сборщиками

MapLibre GL JS рассчитан на работу в сборочных системах, поддерживающих ES Modules.

Vite

Vite автоматически обрабатывает импорт CSS и ESM-модулей:

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

export function initMap() {
  return new maplibregl.Map({
    container: "map",
    style: "https://demotiles.maplibre.org/style.json",
    center: [0, 0],
    zoom: 2
  });
}

Дополнительная конфигурация обычно не требуется.

Webpack

В Webpack-проектах необходимо убедиться, что обработка CSS включена через соответствующие loaders.

Базовая конфигурация:

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

Импорт библиотеки остаётся стандартным:

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

Поддержка TypeScript

MapLibre GL JS содержит встроенные типы TypeScript, поэтому дополнительная установка @types не требуется.

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

import maplibregl from "maplibre-gl";

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

Типы обеспечивают автодополнение для:

  • методов управления картой
  • событий (load, move, click)
  • объектов Marker, Popup, GeoJSONSource

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

Иногда CSS импортируется не через JavaScript, а через глобальное подключение.

Через index.html

<link
  rel="stylesheet"
  href="node_modules/maplibre-gl/dist/maplibre-gl.css"
/>

Такой подход используется реже, но может применяться в проектах без сборщика.

Особенности ESM-сборки

MapLibre GL JS поставляется как ES Module, что влияет на структуру импорта и tree-shaking.

Особенности:

  • поддержка статического анализа импортов
  • удаление неиспользуемых частей при сборке
  • отсутствие необходимости подключать UMD-бандлы

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

import { Map, NavigationControl } from "maplibre-gl";

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

map.addControl(new NavigationControl());

Работа в среде Node.js и SSR

MapLibre GL JS зависит от WebGL и DOM API, поэтому не может выполняться на сервере напрямую. В SSR-средах требуется условная инициализация.

let map;

if (typeof window !== "undefined") {
  import("maplibre-gl").then((maplibregl) => {
    map = new maplibregl.Map({
      container: "map",
      style: "https://demotiles.maplibre.org/style.json"
    });
  });
}

Такой подход предотвращает ошибки при серверном рендеринге.

Контроль версии пакета

Установка через npm фиксирует версию, что важно для стабильности отображения карт.

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

npm list maplibre-gl

Обновление:

npm update maplibre-gl

Установка конкретной версии:

npm install maplibre-gl@3.6.0

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

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

  • dist/maplibre-gl.js — основной бандл
  • dist/maplibre-gl.css — стили
  • dist/maplibre-gl.d.ts — TypeScript определения
  • вспомогательные ресурсы для сборки

Эта структура позволяет использовать библиотеку как в ESM, так и в legacy-сборках при необходимости.

Интеграция с компонентным подходом

В архитектуре SPA библиотека обычно инициализируется внутри компонентов.

Пример абстрактного компонента:

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

export function createMap(containerId) {
  const map = new maplibregl.Map({
    container: containerId,
    style: "https://demotiles.maplibre.org/style.json",
    center: [30, 60],
    zoom: 3
  });

  return map;
}

Такой подход позволяет переиспользовать и изолировать инициализацию карты внутри UI-слоя приложения.

Оглавление