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

Библиотека Deck.gl распространяется как набор модульных пакетов, которые устанавливаются через стандартные менеджеры зависимостей JavaScript. Основной способ интеграции в проект — установка через npm, так как он является де-факто стандартом для экосистемы Node.js и фронтенд-сборок.

Перед установкой требуется наличие окружения Node.js. Проверка выполняется командой:

node -v
npm -v

Если версии отображаются, среда готова к работе.

Установка базового пакета Deck.gl:

npm install @deck.gl/core

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

npm install deck.gl

Пакет deck.gl является мета-пакетом, включающим набор основных модулей:

  • @deck.gl/core — ядро библиотеки, управляющее сценой и рендерингом
  • @deck.gl/layers — набор визуальных слоёв
  • @deck.gl/react — интеграция с React
  • дополнительные утилиты и расширения

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

npm install @deck.gl/core @deck.gl/layers

Подключение в проект после установки npm

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

import {Deck} from '@deck.gl/core';
import {ScatterplotLayer} from '@deck.gl/layers';

В современных сборщиках (Vite, Webpack, Rollup) дополнительных настроек обычно не требуется, так как Deck.gl полностью поддерживает ESM-формат.

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

Yarn используется как альтернатива npm и обеспечивает предсказуемое разрешение зависимостей. Процесс установки идентичен по логике, но отличается командой менеджера пакетов.

Проверка наличия Yarn:

yarn -v

Установка полного пакета Deck.gl:

yarn add deck.gl

Установка минимального набора модулей:

yarn add @deck.gl/core @deck.gl/layers

Yarn автоматически создаёт файл yarn.lock, фиксирующий версии зависимостей, что важно для стабильности графических приложений, где даже небольшие изменения в рендеринге могут приводить к визуальным расхождениям.

Сравнение подходов установки npm и yarn

Оба менеджера выполняют одинаковую задачу — управление зависимостями, однако различаются внутренней логикой:

  • npm использует package-lock.json
  • yarn использует yarn.lock
  • npm устанавливается вместе с Node.js
  • yarn требует отдельной установки (в классической конфигурации)

С точки зрения Deck.gl различий в работе библиотеки нет, так как конечный результат установки идентичен — доступ к модулям через node_modules.

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

После установки формируется набор директорий и модулей, отражающих модульную архитектуру библиотеки.

Типичная структура:

node_modules/
  @deck.gl/
    core/
    layers/
    aggregation-layers/
    geo-layers/

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

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

Версионность и совместимость

Deck.gl тесно связан с WebGL-экосистемой и библиотекой Web Mercator картографии, поэтому версии пакетов следует синхронизировать.

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

npm install deck.gl@8.9.0

или через yarn:

yarn add deck.gl@8.9.0

Несовпадение версий между @deck.gl/core и @deck.gl/layers может привести к ошибкам рендеринга или отсутствию некоторых методов API.

Установка в проектах React

Для React-проектов дополнительно используется пакет интеграции:

npm install @deck.gl/react

или:

yarn add @deck.gl/react

После установки компонент DeckGL можно использовать как обёртку:

import DeckGL from '@deck.gl/react';
import {ScatterplotLayer} from '@deck.gl/layers';

const layers = [
  new ScatterplotLayer({
    id: 'points',
    data: [],
    getPosition: d => d.position,
    getRadius: 1000,
    getFillColor: [255, 0, 0]
  })
];

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

Базовая проверка заключается в импорте модулей без ошибок сборки:

import {Deck} from '@deck.gl/core';

console.log(Deck);

Если объект Deck доступен, установка выполнена корректно.

Установка в monorepo и workspace окружениях

В архитектуре монорепозиториев установка Deck.gl выполняется на уровне workspace:

npm:

npm install deck.gl -w frontend

yarn:

yarn workspace frontend add deck.gl

Такая структура позволяет централизованно управлять зависимостями при разработке сложных визуализационных систем.

Особенности установки в production-сборках

В production-среде часто применяется tree-shaking, и Deck.gl корректно поддерживает удаление неиспользуемых модулей.

Рекомендуется импортировать только необходимые слои:

import {Deck} from '@deck.gl/core';
import {LineLayer} from '@deck.gl/layers';

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

Типичные ошибки при установке

Часто встречаются следующие проблемы:

  • конфликт версий React и @deck.gl/react
  • установка только deck.gl без peer-зависимостей в старых сборках
  • отсутствие поддержки WebGL в среде исполнения
  • смешивание CommonJS и ESM импортов

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

Оглавление