Skip to content

Getting started

Jump to bottom
Dennis Bauszus edited this page Sep 26, 2025 · 11 revisions

Git and Node.js must be installed on your locale to get started.

This guide assumes that you have an IDE like Visual Studio Code installed on your local machine.

Please visit the Get Started with Codespaces wiki page to do the same exercise in the browser.

Clone the repository

You will only require the main branch unless you want to dig into the XYZ development legacy.

git clone https://github.com/GEOLYTIX/xyz --branch main --single-branch xyz-main

Install node modules

Step into the repository root and run the npm install command to install all node module dependencies.

npm install

Build the library

The mapp and ui library must be build. Esbuild will be installed from npm in the previous step. The build script is defined as _build in the package.json and can be executed with npm.

npm run _build

Build documentation

The XYZ/Mapp API documentation can be build from the JSDoc definitions in the script.

npm run generate-docs

No accessible layers in locale!

Express.js will be installed by npm as a development dependency. You can now run a zero config instance by loading the express.js script in your node runtime.

node express.js

The default port is 3000. You can access the mapp interface in your browser on localhost:3000. However there will not be any locale or layer to display yet.

image

The API documentation will be hosted from /xyz path.

image

VSCODE

You can open the cloned repository folder in VSCODE.

Creating a workspace

Lets create the workspace.json file with a locale that has an OSM tile layer.

{
  "locale": {
    "layers": {
      "OSM": {
        "display": true,
        "format": "tiles",
        "URI": "https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png",
        "attribution": {
          "© OpenStreetMap": "http://www.openstreetmap.org/copyright"
        }
      }
    }
  }
}

image

Creating a launch.json

The VSCode Run and Debug panel provides the option to create a new node.js environment.

Set express.js as the program to launch.

Configure a process environment [env{}] for your launch configuration and change the name to 'Hello OSM!'.

In the process env configure the workspace we created in the public folder, and set a title for the instance.

The workspace is a JSON object which can be stored as a file in the public directory. Create a workspace.json file in the public directory and reference this file in WORKSPACE environment variable.

"TITLE": "Hello OSM!",
"WORKSPACE": "file:/public/workspace.json"

image

Once launched the mapp default view will request the locale with the OSM layer from the XYZ [local]host on port 3000.

image

Add a Neon Postgis layer to the workspace

Clone this wiki locally