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

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

Библиотека Mapbox GL JS распространяется как npm-пакет и может быть установлена стандартным способом через менеджер пакетов Node.js.

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

npm install mapbox-gl

После выполнения команды пакет mapbox-gl добавляется в зависимости проекта и становится доступен для импорта в JavaScript-коде.

При использовании yarn эквивалентная команда выглядит следующим образом:

yarn add mapbox-gl

Пакет включает в себя:

  • основной модуль рендеринга карт
  • стили и шейдеры WebGL
  • вспомогательные утилиты
  • типизацию (в современных версиях — частично)

После установки структура проекта в node_modules/mapbox-gl содержит собранный дистрибутив, который предназначен для работы в браузере.

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

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

import mapboxgl from 'mapbox-gl';

Также возможен CommonJS-формат:

const mapboxgl = require('mapbox-gl');

Однако при использовании webpack предпочтение обычно отдаётся ES Modules, так как это обеспечивает лучшую оптимизацию дерева зависимостей (tree shaking).

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

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

Импорт в Jav * aScript:

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

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

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

Базовая настройка webpack для Mapbox GL JS

Webpack должен быть настроен на обработку JavaScript и CSS. Минимальная конфигурация включает:

const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist')
  },
  mode: 'development'
};

Этого недостаточно для корректной работы Mapbox GL JS, так как библиотека использует WebGL, Web Workers и внешние ресурсы.

Настройка обработки CSS

Для работы импортов вида:

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

необходимы loaders:

npm install style-loader css-loader --save-dev

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

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

css-loader интерпретирует CSS как модуль, а style-loader внедряет стили в DOM.

Настройка работы с Web Workers

Mapbox GL JS использует Web Workers для рендеринга тайлов и выполнения тяжёлых вычислений вне основного потока.

При сборке через webpack важно правильно обработать worker-файлы.

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

npm install worker-loader --save-dev

Либо использование встроенной поддержки webpack 5:

module.exports = {
  output: {
    publicPath: ''
  },
  experiments: {
    outputModule: false
  }
};

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

mapboxgl.workerUrl = require('mapbox-gl/dist/mapbox-gl-csp-worker').default;

Это предотвращает ошибки загрузки worker в production-сборках.

Настройка корректной работы в webpack 5

Webpack 5 изменил механику работы с worker-скриптами и файлами ресурсов.

Для Mapbox GL JS часто применяется следующая схема:

import mapboxgl from 'mapbox-gl';
import MapboxWorker from 'mapbox-gl/dist/mapbox-gl-csp-worker';

mapboxgl.workerClass = MapboxWorker;

Такой подход обеспечивает корректную работу WebGL-рендеринга в строгих CSP-окружениях.

Использование API ключа Mapbox

Mapbox GL JS требует токен доступа к API.

Он задаётся глобально:

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

Без корректного токена тайлы и стили загружаться не будут.

Токен применяется ко всем экземплярам карты в текущем приложении.

Создание первой карты в модульной сборке

После настройки webpack и установки зависимостей карта создаётся следующим образом:

import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [37.6173, 55.7558],
  zoom: 10
});

Параметр container указывает DOM-элемент, в который будет встроена карта.

Подключение HTML-контейнера

Webpack не управляет HTML напрямую, поэтому контейнер создаётся в разметке:

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

Стили контейнера критичны для корректного отображения:

#map {
  width: 100%;
  height: 100vh;
}

Без заданной высоты WebGL-контейнер будет иметь нулевую высоту и не отобразится.

Работа с alias и оптимизация зависимостей

При сборке больших приложений рекомендуется настраивать alias для упрощения импортов:

module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src/')
    }
  }
};

Для Mapbox GL JS иногда применяется исключение из оптимизации:

module.exports = {
  module: {
    rules: [
      {
        test: /mapbox-gl/,
        sideEffects: true
      }
    ]
  }
};

Это предотвращает случайное удаление необходимых побочных эффектов, связанных с WebGL и worker-инициализацией.

Обработка статических ресурсов Mapbox GL JS

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

Webpack должен корректно обрабатывать такие ресурсы:

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|svg|woff|woff2)$/,
        type: 'asset/resource'
      }
    ]
  }
};

Это позволяет корректно загружать glyphs и sprite-изображения, используемые стилями Mapbox.

Настройка production-сборки

В production-режиме важно минимизировать bundle и обеспечить корректную работу WebGL:

module.exports = {
  mode: 'production',
  optimization: {
    minimize: true,
    splitChunks: {
      chunks: 'all'
    }
  }
};

Дополнительно часто используется отключение source maps или их перенос в отдельные файлы:

devtool: 'source-map'

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

При работе с Mapbox GL JS в сборке часто возникают специфические ошибки:

  • ошибка загрузки Web Worker из-за неверного пути
  • отсутствие стилей из-за не подключённого CSS loader
  • белый экран из-за отсутствующего контейнера или высоты
  • невозможность загрузки тайлов при отсутствии access token
  • конфликт CSP-политики при загрузке ресурсов

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

Поддержка ESNext и транспиляция

Mapbox GL JS распространяется в современном синтаксисе JavaScript, поэтому при необходимости транспиляции используется Babel:

npm install babel-loader @babel/core @babel/preset-env --save-dev

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

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      }
    ]
  }
};

Итоговая структура проекта

Типичная структура проекта с Mapbox GL JS и webpack:

project/
 ├─ src/
 │   ├─ index.js
 │   └─ styles.css
 ├─ dist/
 ├─ webpack.config.js
 ├─ package.json
 └─ index.html

Такая организация обеспечивает предсказуемую сборку и корректную работу WebGL-карты в браузере.

Оглавление