Интеграция в существующий проект

Интеграция Kepler.gl в уже существующий проект почти всегда сводится к аккуратному встраиванию его Redux-слоя и React-компонента в текущую архитектуру приложения. Библиотека построена вокруг состояния, поэтому ключевая задача — не конфликтовать с уже существующим store и корректно подключить редьюсеры и middleware.

Базовая точка входа — установка зависимостей:

npm install kepler.gl react-map-gl mapbox-gl redux react-redux

Kepler.gl опирается на react-map-gl и Mapbox (или альтернативные tile-сервисы), поэтому важно заранее учитывать требования к токенам и конфигурации карт.

Подключение редьюсера Kepler.gl в существующий Redux store

Если проект уже использует Redux, Kepler.gl интегрируется как дополнительный редьюсер:

import { createStore, combineReducers, applyMiddleware } from 'redux';
import keplerGlReducer from 'kepler.gl/reducers';

const rootReducer = combineReducers({
  keplerGl: keplerGlReducer,
  // другие редьюсеры приложения
});

const store = createStore(rootReducer, applyMiddleware(/* middleware */));

Критический момент — ключ keplerGl должен быть сохранён, так как внутренняя логика библиотеки ожидает именно такую структуру состояния.

Подключение middleware для работы с асинхронными действиями

Kepler.gl использует набор action creators, работающих с асинхронными процессами (загрузка данных, обновление конфигураций, обработка слоёв).

import keplerGlMiddleware from 'kepler.gl/middleware';

const store = createStore(
  rootReducer,
  applyMiddleware(
    keplerGlMiddleware
  )
);

Middleware обеспечивает корректную обработку действий вроде добавления датасета или обновления визуальных слоёв без необходимости ручного управления side effects.

Встраивание компонента карты в интерфейс приложения

После настройки store можно подключить основной компонент:

import KeplerGl from 'kepler.gl';

function MapContainer() {
  return (
    <div style={{ height: '100vh', width: '100%' }}>
      <KeplerGl
        id="map"
        mapboxApiAccessToken={process.env.MAPBOX_TOKEN}
        width={window.innerWidth}
        height={window.innerHeight}
      />
    </div>
  );
}

Идентификатор id критически важен: он используется для изоляции нескольких экземпляров карт внутри одного приложения.

Интеграция в существующую структуру приложения

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

  • синхронизация состояния с внешними фильтрами
  • управление слоями из UI приложения
  • загрузка данных из собственного backend
  • сохранение конфигураций карты

Типовой паттерн — подключение контейнерного компонента через connect:

import { connect } from 'react-redux';
import KeplerGl from 'kepler.gl';

const Map = connect()(KeplerGl);

Это позволяет использовать стандартный Redux-flow без нарушения внутренней логики библиотеки.

Передача данных в карту из внешнего источника

Добавление данных осуществляется через actions:

import { addDataToMap } from 'kepler.gl/actions';

dispatch(
  addDataToMap({
    datasets: {
      info: {
        label: 'My dataset',
        id: 'my_dataset'
      },
      data: geojsonData
    },
    options: {
      centerMap: true,
      readOnly: false
    }
  })
);

Данные могут приходить из REST API, WebSocket или локальных файлов. Важно учитывать формат: Kepler.gl поддерживает CSV, GeoJSON и специализированные структуры.

Интеграция с существующим API и backend-слоем

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

  1. Backend возвращает GeoJSON или таблицы
  2. Frontend нормализует данные
  3. Kepler.gl получает данные через addDataToMap

Пример загрузки:

async function loadMapData() {
  const res = await fetch('/api/geo-data');
  const data = await res.json();

  dispatch(addDataToMap({
    datasets: {
      info: { id: 'server_data', label: 'Server Data' },
      data
    }
  }));
}

Сохранение и восстановление конфигурации карты

Одна из ключевых возможностей интеграции — сериализация состояния карты.

import { exportFile } from 'kepler.gl/actions';

// экспорт конфигурации
dispatch(exportFile());

// восстановление
dispatch(
  addDataToMap(savedState)
);

Конфигурация включает слои, фильтры, стили и положение камеры. Это позволяет реализовать:

  • сохранение пользовательских карт
  • шаринг визуализаций
  • восстановление состояния после перезагрузки

Работа с несколькими экземплярами карт

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

<KeplerGl id="mapA" />
<KeplerGl id="mapB" />

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

state.keplerGl.mapA
state.keplerGl.mapB

Это особенно важно для дашбордов и аналитических систем.

Интеграция в Next.js и SSR-окружения

Kepler.gl использует browser APIs, поэтому серверный рендеринг требует отключения SSR для карты:

import dynamic from 'next/dynamic';

const KeplerGl = dynamic(
  () => import('kepler.gl'),
  { ssr: false }
);

Также важно избегать обращения к window до монтирования компонента.

Работа со стилями и конфликтами CSS

Kepler.gl включает собственные стили Mapbox и UI-компонентов. В интегрированном проекте часто возникают конфликты:

  • z-index слоёв интерфейса
  • глобальные reset-стили
  • пересечения с UI библиотеками (MUI, Ant Design)

Рекомендуется изолировать контейнер:

.kepler-map-wrapper {
  position: relative;
  height: 100vh;
  overflow: hidden;
}

Производительность при встраивании в крупные приложения

При интеграции в сложные системы основная нагрузка возникает на:

  • рендер WebGL слоёв
  • обработку больших GeoJSON
  • синхронизацию Redux state

Практические подходы:

  • ленивое подключение компонента карты
  • мемоизация данных перед передачей
  • отключение ненужных слоёв
  • использование упрощённых геометрий

Синхронизация состояния карты с внешними UI компонентами

Kepler.gl позволяет строить связанный интерфейс, где фильтры и контролы приложения управляют картой:

dispatch(
  updateMap({
    zoom: 10,
    latitude: 50.45,
    longitude: 30.52
  })
);

Такой подход используется в аналитических панелях, где карта — лишь один из модулей.

Встраивание в существующие дизайн-системы

При интеграции в UI системы важно учитывать, что Kepler.gl:

  • имеет собственный layout менеджер
  • использует fixed positioning для панели инструментов
  • управляет собственными модальными окнами

Часто требуется:

  • скрытие ненужных панелей
  • кастомизация темы через config
  • ограничение доступа к функциям UI

Типовые ошибки при интеграции

  • конфликт Redux store из-за неправильного ключа keplerGl
  • отсутствие Mapbox token
  • попытка SSR без отключения клиента
  • передача некорректного формата данных
  • пересоздание store при каждом рендере

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

Архитектурные паттерны использования в больших системах

В масштабируемых приложениях Kepler.gl чаще всего встраивается по одному из сценариев:

  • как отдельный feature-module внутри microfrontend архитектуры
  • как аналитический слой поверх существующего dashboard
  • как отдельная страница с ленивой загрузкой
  • как embedded-компонент с ограниченным API управления

Во всех случаях ключевым остаётся принцип: состояние карты должно быть изолировано, но управляемо извне через Redux actions.

Оглавление