Установка через npm и сборщики модулей

При использовании HERE Maps API в современных веб-приложениях всё чаще применяется установка через npm вместо подключения скриптов из CDN. Такой подход обеспечивает более удобное управление зависимостями, лучшую интеграцию со сборщиками модулей и возможность использовать возможности экосистемы JavaScript.

Менеджер пакетов npm позволяет:

  • централизованно управлять версиями библиотек;
  • контролировать зависимости проекта;
  • использовать модульную архитектуру;
  • уменьшать размер итоговой сборки;
  • интегрировать карты в приложения на React, Vue, Angular и других фреймворках;
  • автоматизировать процесс разработки и развертывания.

Вместо прямого подключения внешних скриптов через HTML-разметку библиотека устанавливается в каталог проекта и становится частью системы сборки.

Подготовка окружения

Перед установкой необходимо наличие следующих компонентов:

  • Node.js;
  • npm (устанавливается вместе с Node.js);
  • современного сборщика модулей;
  • редактора кода.

Проверка установленных версий:

node -v
npm -v

Создание нового проекта:

mkdir here-maps-project
cd here-maps-project
npm init -y

После выполнения команды появится файл:

package.json

Он содержит информацию о проекте и список зависимостей.

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

HERE предоставляет JavaScript API через пакет:

npm install @here/maps-api-for-javascript

После установки зависимость автоматически добавляется в файл package.json:

{
  "dependencies": {
    "@here/maps-api-for-javascript": "^1.x.x"
  }
}

Пакет помещается в каталог:

node_modules/

Структура проекта может выглядеть следующим образом:

project/
│
├── node_modules/
├── src/
│   ├── main.js
│   └── styles.css
│
├── package.json
└── vite.config.js

Использование ES-модулей

Современные сборщики работают с системой модулей ES Modules.

Пример импорта:

import H from '@here/maps-api-for-javascript';

После импорта становится доступно пространство имён HERE:

const platform = new H.service.Platform({
    apikey: 'YOUR_API_KEY'
});

Получение объекта карты:

const defaultLayers = platform.createDefaultLayers();

const map = new H.Map(
    document.getElementById('map'),
    defaultLayers.vector.normal.map,
    {
        zoom: 10,
        center: { lat: 55.7558, lng: 37.6176 }
    }
);

Такой подход отличается от классического подключения через глобальный объект window.H, поскольку все зависимости импортируются явно.

Установка и настройка Vite

Vite является одним из наиболее популярных инструментов сборки для современных веб-приложений.

Создание проекта:

npm create vite@latest here-vite

Переход в каталог:

cd here-vite

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

npm install

Установка HERE Maps:

npm install @here/maps-api-for-javascript

Запуск сервера разработки:

npm run dev

Использование HERE Maps в Vite

Файл:

src/main.js

Содержимое:

import H from '@here/maps-api-for-javascript';

const platform = new H.service.Platform({
    apikey: 'YOUR_API_KEY'
});

const defaultLayers = platform.createDefaultLayers();

const map = new H.Map(
    document.getElementById('map'),
    defaultLayers.vector.normal.map,
    {
        zoom: 12,
        center: {
            lat: 48.8566,
            lng: 2.3522
        }
    }
);

window.addEventListener('resize', () => {
    map.getViewPort().resize();
});

HTML-шаблон:

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

CSS:

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

После запуска проекта карта будет отображаться через систему модулей Vite.

Работа с Webpack

Webpack остаётся одним из самых распространённых сборщиков для крупных приложений.

Установка:

npm install webpack webpack-cli webpack-dev-server --save-dev

Установка HERE Maps:

npm install @here/maps-api-for-javascript

Создание конфигурационного файла:

const path = require('path');

module.exports = {
    mode: 'development',

    entry: './src/index.js',

    output: {
        filename: 'bundle.js',
        path: path.resolve(__dirname, 'dist')
    },

    devServer: {
        static: './dist'
    }
};

Запуск:

npx webpack serve

Подключение карты в Webpack-проекте

Файл:

import H from '@here/maps-api-for-javascript';

const platform = new H.service.Platform({
    apikey: 'YOUR_API_KEY'
});

const layers = platform.createDefaultLayers();

const map = new H.Map(
    document.getElementById('map'),
    layers.vector.normal.map,
    {
        center: {
            lat: 40.7128,
            lng: -74.0060
        },
        zoom: 11
    }
);

Webpack включит библиотеку в итоговый пакет:

bundle.js

Браузеру больше не потребуется отдельно загружать несколько внешних файлов API.

Использование в React

Установка:

npm install @here/maps-api-for-javascript

Компонент карты:

import { useEffect, useRef } from 'react';
import H from '@here/maps-api-for-javascript';

export default function HereMap() {

    const mapRef = useRef(null);

    useEffect(() => {

        const platform = new H.service.Platform({
            apikey: 'YOUR_API_KEY'
        });

        const layers = platform.createDefaultLayers();

        const map = new H.Map(
            mapRef.current,
            layers.vector.normal.map,
            {
                center: {
                    lat: 51.5074,
                    lng: -0.1278
                },
                zoom: 12
            }
        );

        return () => {
            map.dispose();
        };

    }, []);

    return (
        <div
            ref={mapRef}
            style={{
                width: '100%',
                height: '500px'
            }}
        />
    );
}

Особое внимание следует уделять очистке ресурсов через:

map.dispose();

Это предотвращает утечки памяти после удаления компонента.

Использование в Vue

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

<template>
  <div ref="mapContainer" class="map"></div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import H from '@here/maps-api-for-javascript';

const mapContainer = ref(null);

let map;

onMounted(() => {

    const platform = new H.service.Platform({
        apikey: 'YOUR_API_KEY'
    });

    const layers = platform.createDefaultLayers();

    map = new H.Map(
        mapContainer.value,
        layers.vector.normal.map,
        {
            zoom: 10,
            center: {
                lat: 52.52,
                lng: 13.405
            }
        }
    );
});

onUnmounted(() => {
    map.dispose();
});
</script>

<style>
.map {
    width: 100%;
    height: 500px;
}
</style>

Использование в Angular

Установка:

npm install @here/maps-api-for-javascript

Компонент:

import { Component, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
import H from '@here/maps-api-for-javascript';

@Component({
    selector: 'app-map',
    template: '<div #mapContainer></div>'
})
export class MapComponent implements AfterViewInit {

    @ViewChild('mapContainer')
    mapElement!: ElementRef;

    ngAfterViewInit() {

        const platform = new H.service.Platform({
            apikey: 'YOUR_API_KEY'
        });

        const layers = platform.createDefaultLayers();

        new H.Map(
            this.mapElement.nativeElement,
            layers.vector.normal.map,
            {
                zoom: 13,
                center: {
                    lat: 35.6762,
                    lng: 139.6503
                }
            }
        );
    }
}

Инициализация выполняется после создания DOM-элемента карты.

Хранение API-ключа через переменные окружения

Жёсткое указание ключа внутри исходного кода считается плохой практикой.

Пример файла:

.env

Содержимое:

VITE_HERE_API_KEY=your_key

Использование в Vite:

const platform = new H.service.Platform({
    apikey: import.meta.env.VITE_HERE_API_KEY
});

Для Webpack часто используется пакет:

npm install dotenv

Загрузка переменных:

require('dotenv').config();

Использование:

process.env.HERE_API_KEY

Такой подход облегчает перенос проекта между различными средами разработки.

Tree Shaking и оптимизация сборки

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

Преимущества:

  • уменьшение размера бандла;
  • ускорение загрузки приложения;
  • сокращение потребления памяти;
  • повышение производительности.

Для корректной работы оптимизации рекомендуется:

  • использовать ES-модули;
  • избегать глобальных подключений;
  • импортировать только необходимые части API;
  • использовать production-сборку.

Пример production-сборки в Vite:

npm run build

Пример для Webpack:

npx webpack --mode production

Разделение кода через динамический импорт

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

Для уменьшения первоначального объёма загрузки применяется динамический импорт.

const H = await import(
    '@here/maps-api-for-javascript'
);

Ленивая загрузка карты:

async function initMap() {

    const module = await import(
        '@here/maps-api-for-javascript'
    );

    const H = module.default;

    const platform = new H.service.Platform({
        apikey: 'YOUR_API_KEY'
    });

}

В этом случае код HERE Maps попадёт в отдельный чанк и будет загружаться только при необходимости.

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

Ошибка импорта

Сообщение:

Module not found

Причины:

  • пакет не установлен;
  • повреждены зависимости;
  • неверный путь импорта.

Решение:

npm install

или

npm install @here/maps-api-for-javascript

Карта не отображается

Распространённые причины:

  • отсутствует API-ключ;
  • неверный API-ключ;
  • контейнер имеет нулевую высоту;
  • карта создаётся до появления DOM-элемента.

Проверка контейнера:

#map {
    height: 500px;
}

Ошибка CORS

Иногда возникает при использовании дополнительных сервисов платформы.

Проверяются:

  • настройки проекта в HERE Platform;
  • разрешённые домены;
  • корректность ключа доступа.

Проблемы после сборки

В режиме разработки карта работает, а после production-сборки перестаёт отображаться.

Наиболее частые причины:

  • неверная работа с переменными окружения;
  • отсутствие некоторых ресурсов в сборке;
  • ошибки маршрутизации SPA-приложения;
  • неправильная конфигурация Webpack или Vite.

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

Организация структуры проекта

Для крупных приложений рекомендуется выделять работу с HERE Maps в отдельные модули.

Пример структуры:

src/
│
├── maps/
│   ├── here.js
│   ├── markers.js
│   ├── routing.js
│   ├── geocoding.js
│   └── layers.js
│
├── components/
│
├── services/
│
└── app.js

Файл инициализации платформы:

import H from '@here/maps-api-for-javascript';

export const platform =
    new H.service.Platform({
        apikey: import.meta.env.VITE_HERE_API_KEY
    });

Повторное использование:

import { platform } from './maps/here';

Подобная организация облегчает сопровождение проекта, масштабирование функциональности картографического приложения и интеграцию HERE Maps API в сложные современные JavaScript-системы, построенные на базе npm и модульных сборщиков.

Оглавление