GuidesKB Articles
Guides
  1. Getting Started

Working with Angular + HARP engine: step by step

When integrating HERE Maps API for JavaScript 3.x with an Angular application and the HARP rendering engine, customers may see a blank map, missing UI controls, resize issues, TypeScript compilation errors, or an application that starts successfully but does not render map tiles.

This article explains how to create an Angular project, install the @here/maps-api-for-javascript package, configure TypeScript, add a reusable map component, enable the HARP engine, include the HERE UI CSS, and start the application.

Symptoms / Triggers

You may need this article if you experience any of the following:

  • Angular application starts, but the HERE map area is blank or has zero height.
  • Map tiles do not render after adding @here/maps-api-for-javascript.
  • HARP engine is not used, or H.Map.EngineType['HARP'] is not configured.
  • TypeScript or Angular compilation fails after importing @here/maps-api-for-javascript/bin/mapsjs.bundle.harp.
  • The HERE UI controls are missing or incorrectly styled because mapsjs-ui.css is not included in angular.json.
  • The map does not resize correctly when the Angular component or browser window changes size.
  • On Windows, Angular CLI commands fail because PowerShell script execution is restricted.

Quick Answer

To use HERE Maps API for JavaScript with Angular and the HARP engine, install @here/maps-api-for-javascript, import @here/maps-api-for-javascript/bin/mapsjs.bundle.harp, create the map in ngAfterViewInit(), set engineType: H.Map.EngineType['HARP'], give the map container a real height, include mapsjs-ui.css in angular.json, and call map.getViewPort().resize() when the container size changes.

If the map is blank, first verify the API key, the map container height, the HARP bundle import, the Angular styles configuration, and browser console errors.

Step-by-step Solution

1. Create a new Angular project

Make sure Angular CLI is installed. Then create a new Angular project and open the project folder.

ng new jsapi-angular-harpcd jsapi-angular-harp

Note for Windows users: if Angular CLI commands are blocked in PowerShell, open PowerShell as Administrator and run Set-ExecutionPolicy RemoteSigned before running ng new jsapi-angular-harp.

2. Configure the HERE NPM registry and install Maps API for JavaScript

The @here/maps-api-for-javascript package is hosted in the HERE NPM registry. Add the HERE registry entry first:

npm config set "@here:registry" "https://repo.platform.here.com/artifactory/api/npm/maps-api-for-javascript/"

Then install the package:

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

3. Update TypeScript configuration

Open tsconfig.json and add the following setting under angularCompilerOptions. This helps avoid import-related TypeScript issues in Angular projects.

"allowSyntheticDefaultImports": true

4. Generate the Angular map component

ng generate component jsmap

Open src/app/jsmap/jsmap.component.ts and replace the default code with the following component implementation.

import { Component, ViewChild, ElementRef } from '@angular/core';import '@here/maps-api-for-javascript/bin/mapsjs.bundle.harp';import onResize from 'simple-element-resize-detector';@Component({  selector: 'app-jsmap',  templateUrl: './jsmap.component.html',  styleUrls: ['./jsmap.component.css'],  standalone: true})export class JsmapComponent {  private map?: H.Map;  @ViewChild('map') mapDiv?: ElementRef;  ngAfterViewInit(): void {    if (!this.map && this.mapDiv) {      const engineType = H.Map.EngineType['HARP'];      const platform = new H.service.Platform({        apikey: 'your apikey created on platform.here.com'      });      const layers = platform.createDefaultLayers({        engineType: engineType      });      const map = new H.Map(        this.mapDiv.nativeElement,        (layers as any).vector.normal.map,        {          engineType: engineType,          pixelRatio: window.devicePixelRatio,          center: {lat: 0, lng: 0},          zoom: 2        }      );      this.map = map;      onResize(this.mapDiv.nativeElement, () => {        map.getViewPort().resize();      });      // Enable map events and default interactions such as pan and zoom.      var behavior = new H.mapevents.Behavior(new H.mapevents.MapEvents(map));      // Create the default UI controls.      var ui = H.ui.UI.createDefault(map, layers);    }  }}

5. Add the map component to the Angular application

If your application uses standalone components, make sure JsmapComponent is imported in app.component.ts or the appropriate parent component. Then open src/app/app.component.html and replace the content with:

<app-jsmap>app-jsmap>

6. Add the map container HTML

Open src/app/jsmap/jsmap.component.html and replace the file content with:

 #map id="map">

7. Set the map container size

A blank map is often caused by the map container having no height. Open src/app/jsmap/jsmap.component.css and add:

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

Then open src/styles.css and add global height styles:

/* Global application styles */html,body {    width: 100%;    height: 100%;}

8. Install the resize detector dependency

The resize detector is used to call map.getViewPort().resize() when the map container size changes.

npm install simple-element-resize-detector --savenpm install @types/simple-element-resize-detector --save-dev

9. Add HERE UI CSS to angular.json

If you create the default UI with H.ui.UI.createDefault(map, layers), include the HERE UI CSS file in the styles array in angular.json.

"styles": [  "src/styles.css",  "node_modules/@here/maps-api-for-javascript/bin/mapsjs-ui.css"]

10. Start the Angular application

ng cache cleanng serve

Open the local Angular development URL in the browser and verify that the map appears, can be panned and zoomed, and displays the HERE UI controls.

Troubleshooting Checklist

  • If the map is blank, confirm that #map, html, and body have a valid height.
  • If HARP is not used, confirm the import @here/maps-api-for-javascript/bin/mapsjs.bundle.harp and the setting engineType: H.Map.EngineType['HARP'].
  • If UI controls are missing or unstyled, confirm that node_modules/@here/maps-api-for-javascript/bin/mapsjs-ui.css is included in angular.json.
  • If the map does not resize, confirm that simple-element-resize-detector is installed and map.getViewPort().resize() is called.
  • If tiles fail to load, verify that the API key was created on platform.here.com and is valid for Maps API for JavaScript.

Applies To

  • HERE Maps API for JavaScript 3.x
  • HERE Maps API for JavaScript 3.1.43.0 and later 3.x versions
  • Angular applications using Angular CLI
  • HARP rendering engine
  • @here/maps-api-for-javascript NPM package
  • Browser-based TypeScript and JavaScript frontend applications

Documentation

Angular practices for HERE Maps API for JavaScript: https://docs.here.com/maps-api-for-js/docs/angular-practices

HERE NPM registry: https://repo.platform.here.com/

Searchable Tags / Keywords

Angular blank map, HERE Maps Angular, Angular HARP engine, HARP not loading, map not rendering Angular, HERE Maps API for JavaScript 3.x, Maps JS 3.1.43, @here/maps-api-for-javascript, mapsjs.bundle.harp, H.Map.EngineType HARP, platform.createDefaultLayers, vector.normal.map, H.ui.UI.createDefault, mapsjs-ui.css, angular.json styles, map container height, #map height 100%, map.getViewPort resize, simple-element-resize-detector, TypeScript allowSyntheticDefaultImports, API key platform.here.com, Angular standalone component, HERE map tiles not loading