XYZ Maps JS

XYZ Maps is an experimental and work in progress open-source map editor written in TypeScript/JavaScript.

• API Playground
• Documentation

Overview

XYZ Maps consists of the following main modules:

• @here/xyz-maps-common : The Common module provides commonly used javascript functionality that is required by all other modules of XYZ Maps.
• @here/xyz-maps-core : The Core module provides the most basic functionality. Main functionalities of the module are: DataProviders, TileLayers, Geometric Classes and Styling definitions.
• @here/xyz-maps-display : The Display module is a highly customizable vector map display that's optimized for map editing, larger raw datasets and frequently changing data.
• @here/xyz-maps-editor : The Editor module provides an API for editing map data that can be used to easily access, add, remove and edit various types of map data.

All four modules provide UMD and ESM builds with TypeScript and browser-global typings.

Prerequisites

• Node.js (version in .nvmrc)
• pnpm (any version, the project pins its own, see below)

Start developing

1. Clone this repository

   git clone https://github.com/heremaps/xyz-maps.git
   
   cd xyz-maps
   

2. Install pnpm, if it is not installed yet

   npm install -g pnpm
   

   The project pins the pnpm version in package.json (packageManager). pnpm switches to that version automatically. Installs with npm or yarn are blocked on purpose.

3. Install node module dependencies

   pnpm install
   

4. watch for source code changes and build dev version

   pnpm run watch-dev
   

   Builds are located in ./packages/*/dist/

Setup your XYZ token

Setup an XYZ token is only required if the XYZ Hub endpoint at xyz.api.here.com is used. You can get a token by following the instructions in this guide.

If you are using a local XYZ Hub simply set set-access-token to an empty string.

Running integration tests / playground and debug pages requires the XYZ token to be provided.

• Configure your XYZ token

  pnpm run set-access-token YOUR_ACCESS_TOKEN
  

Serve debug page

• Start debug server (requires xyz access token)

  pnpm run server
  

  browser will start and open http://localhost:8080/debug automatically

Serve Playground

• Build and start the playground (requires xyz access token)

  pnpm run playground
  

  browser will start and open http://localhost:8081/packages/playground/dist automatically

Other Commands

• Run tests on release build pnpm run test

• Build development version pnpm run build-dev (located in docs/)

• Build release version only pnpm run build-release (minified...)

• Build the documentation pnpm run build-doc (located in packages/docs/dist/)

• Create full release bundle pnpm run bundle-release (includes documentation and playground)

• Configure XYZ access token pnpm run set-access-token YOUR_ACCESS_TOKEN

Guides

• Getting started
• Display your space
• Style your data
• Add interactivity

License

Copyright (C) 2019-2026 HERE Europe B.V.

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details