CDN интеграция

Работа с Kepler.gl через CDN требует понимания того, что библиотека построена на экосистеме React, Redux и WebGL-рендеринге поверх deck.gl. Прямое подключение без сборщика возможно, но требует аккуратной сборки зависимостей через глобальные UMD-бандлы и правильного порядка загрузки скриптов.

CDN-интеграция в контексте Kepler.gl предполагает использование готовых браузерных сборок библиотек:

  • React и ReactDOM как глобальные объекты
  • Redux как контейнер состояния
  • React-Redux для связывания компонентов
  • Kepler.gl как UMD-модуль (через unpkg или jsDelivr)
  • Mapbox GL JS для базовой карты

Ключевая особенность заключается в том, что Kepler.gl не предназначен для «голого» подключения в браузере, поэтому важно соблюдение совместимых версий зависимостей.

Пример подключения через CDN:

<script src="https://unpkg.com/react@17/umd/react.development.js"></script>
<script src="https://unpkg.com/react-dom@17/umd/react-dom.development.js"></script>

<script src="https://unpkg.com/redux@4.2.1/dist/redux.min.js"></script>
<script src="https://unpkg.com/react-redux@7.2.9/dist/react-redux.min.js"></script>

<script src="https://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.css" rel="stylesheet">

Подключение Kepler.gl через CDN:

<script src="https://unpkg.com/kepler.gl@2.5.5/dist/keplergl.min.js"></script>

После загрузки библиотека становится доступной через глобальные объекты, включая KeplerGl, reducers и actions.

Базовая HTML-структура приложения

Для корректной работы требуется контейнер, в который будет монтироваться React-приложение:

<div id="app"></div>

Дополнительно необходимо задать размеры контейнера, иначе карта не отобразится:

<style>
  body {
    margin: 0;
    overflow: hidden;
  }

  #app {
    width: 100vw;
    height: 100vh;
  }
</style>

Инициализация Redux-хранилища

Kepler.gl использует Redux как обязательный слой состояния. В CDN-сценарии он создаётся вручную:

const { createStore, combineReducers, applyMiddleware } = Redux;
const { Provider } = ReactRedux;
const { keplerGlReducer } = KeplerGl;

Создание root reducer:

const reducers = combineReducers({
  keplerGl: keplerGlReducer
});

Создание store:

const store = createStore(reducers, {}, applyMiddleware());

Подготовка Mapbox токена

Kepler.gl требует Mapbox токен для отображения тайлов:

const MAPBOX_TOKEN = "YOUR_MAPBOX_TOKEN";

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

Создание базового React-контейнера

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

const { Component } = React;
const { render } = ReactDOM;
const { KeplerGl } = KeplerGl;

Компонент приложения:

class App extends Component {
  render() {
    return React.createElement(
      KeplerGl,
      {
        id: "map",
        width: window.innerWidth,
        height: window.innerHeight,
        mapboxApiAccessToken: MAPBOX_TOKEN
      },
      null
    );
  }
}

Монтаж приложения

React-приложение подключается через Provider:

render(
  React.createElement(
    Provider,
    { store },
    React.createElement(App)
  ),
  document.getElementById("app")
);

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

Загрузка данных через CDN-режим

Данные можно добавлять напрямую через actions, которые также доступны из глобального объекта:

const { addDataToMap } = KeplerGl.actions;

Пример добавления датасета:

const sampleData = {
  fields: [
    { name: "lat", type: "real" },
    { name: "lng", type: "real" }
  ],
  rows: [
    { lat: 51.5, lng: 0.12 },
    { lat: 40.7, lng: -74.0 }
  ]
};

store.dispatch(
  addDataToMap({
    datasets: {
      info: {
        label: "Points",
        id: "points"
      },
      data: sampleData
    },
    option: {
      centerMap: true,
      readOnly: false
    }
  })
);

Работа с состоянием Kepler.gl в CDN

В отличие от сборочных систем, CDN-режим требует явного контроля store:

  • все изменения проходят через dispatch
  • состояние доступно через store.getState()
  • интеграция с внешними UI-компонентами возможна только через Redux

Пример получения состояния:

console.log(store.getState().keplerGl);

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

Kepler.gl поддерживает несколько экземпляров карты через уникальные id.

React.createElement(KeplerGl, {
  id: "map1",
  width: 600,
  height: 400,
  mapboxApiAccessToken: MAPBOX_TOKEN
});
React.createElement(KeplerGl, {
  id: "map2",
  width: 600,
  height: 400,
  mapboxApiAccessToken: MAPBOX_TOKEN
});

Каждый экземпляр получает собственный slice состояния внутри Redux:

state.keplerGl.map1
state.keplerGl.map2

Частые ограничения CDN-интеграции

CDN-использование накладывает архитектурные ограничения:

  • отсутствие tree-shaking приводит к увеличению веса загрузки
  • сложность версионирования зависимостей
  • необходимость ручного управления глобальными объектами
  • ограниченная совместимость с современными ES-модулями
  • отсутствие удобной работы с TypeScript без дополнительной настройки

Особенно критичным является синхронизация версий React и Kepler.gl, так как несовместимость приводит к ошибкам контекста Redux и некорректной отрисовке слоёв.

Расширение через внешние библиотеки

CDN-интеграция допускает подключение дополнительных визуальных слоёв deck.gl через глобальные расширения:

const { ScatterplotLayer } = deck;

Их можно использовать в кастомных конфигурациях слоёв Kepler.gl через модификацию состояния mapConfig, однако такой подход требует точного соблюдения структуры конфигурации и понимания внутреннего schema.

Организация production-сборки поверх CDN

Даже при использовании CDN часто применяется гибридная схема:

  • UI загружается через CDN
  • данные поступают через API
  • состояние сохраняется на сервере
  • конфигурации карт сериализуются в JSON

Это позволяет использовать Kepler.gl как визуальный слой поверх легковесного веб-приложения без полноценного bundler-пайплайна, сохраняя при этом интерактивность и масштабируемость визуализации геоданных.

Оглавление