Skip to content
jochenklarPublic

About

A web app to compare tiled maps side by side.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

@jochenklar/maps

A web app to compare tiled maps side by side. The screen can be split into panes, each showing a map chosen from a configured list, and all panes move and zoom together. It includes a place search (using Nominatim), geolocation, a coordinate grid and a center marker. The view and the layout of the panes are stored in the url, so that they can be shared.

The app is a React component: a project is a small Vite app, which renders the component with a maps.config.js containing the maps to show, and builds it into a static site.

Setting up a new project

Create a directory with a package.json:

{
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Install this package from npm, React and Vite (Node.js 24 is used for development, see .nvmrc):

npm install @jochenklar/maps react react-dom vite @vitejs/plugin-react

Add a vite.config.js with the React plugin, the options for scss silence the deprecation warnings of Bootstrap:

import { defineConfig } from 'vite'

import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  css: {
    preprocessorOptions: {
      scss: {
        quietDeps: true,
        silenceDeprecations: ['import', 'legacy-js-api', 'global-builtin', 'color-functions'],
      },
    },
  },
})

Add an index.html with the title of the page and, for link previews in messengers and social media, the Open Graph tags, since their crawlers don't run javascript:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Berlin Maps</title>
    <meta property="og:title" content="Berlin Maps" />
    <meta property="og:url" content="https://maps.example.com" />
    <meta property="og:image" content="https://maps.example.com/share.png" />
    <link rel="icon" type="image/svg+xml" href="/icon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/main.jsx"></script>
  </body>
</html>

Add a main.jsx, which renders the app with the config. It imports Bootstrap and its icons, then the styles of the app and then the styles of the project, e.g. a maps.css:

import React, { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { Maps } from '@jochenklar/maps'

import '@jochenklar/maps/bootstrap.scss'
import '@jochenklar/maps/style.scss'
import './maps.css'

import config from './maps.config.js'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <Maps config={config} />
  </StrictMode>,
)

Add a maps.config.js with the maps to show, see Configuration:

export default {
  brand: {
    text: 'Berlin Maps',
  },
  view: {
    center: [52.51, 13.37628],
    zoom: 12,
  },
  maps: [
    {
      name: 'OpenStreetMap',
      url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
      attribution: '<a href="https://www.openstreetmap.org/copyright">OpenStreetMap contributors</a>',
      maxZoom: 19,
    },
    {
      name: 'OpenTopoMap',
      url: 'https://tile.opentopomap.org/{z}/{x}/{y}.png',
      attribution: '<a href="https://opentopomap.org">OpenTopoMap</a> (CC-BY-SA)',
      maxZoom: 17,
    },
  ],
}

Longer HTML for info is easier to keep in its own file, which can be imported as text with ?raw:

import infoDe from './info.de.html?raw'
import infoEn from './info.en.html?raw'

export default {
  info: {
    de: infoDe,
    en: infoEn,
  },
  // ...
}

Similarly, the list of maps, which tends to get long, can be kept in a maps.json and imported:

import maps from './maps.json'

export default {
  maps,
  // ...
}

maps.json then contains the array of maps, like maps above, or of groups with a name and their maps, which are shown under their name in the map selection:

[
  {
    "name": "Maps",
    "maps": [
      {
        "name": "OpenStreetMap",
        "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
        "attribution": "<a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap contributors</a>",
        "maxZoom": 19
      }
    ]
  }
]

Optionally, add a public/ directory for static files, like the favicon. Its content is copied into the build. The maps.css can be used to set the colors with the CSS variables of Bootstrap.

A .gitignore should contain at least:

node_modules/
dist/

The project then looks like this:

my-maps/
├── index.html
├── main.jsx
├── maps.config.js
├── maps.css
├── package.json
├── package-lock.json
├── public/
│   └── icon.svg
└── vite.config.js

Start the development server with npm run dev. npm run build builds the static site into dist/, which can be served by any web server, and npm run preview serves the build locally.

Configuration

The config is merged into the default config, so only the values which differ from the defaults need to be set. Objects are merged, all other values, including arrays like maps, are replaced. With an empty config {}, only the default config is used.

Key Default Description
brand.text The title of the page and of the info, or titles by language like { de, en }. Without it, the <title> from index.html is used.
info HTML which is shown in the info, which opens on the first visit and with the info entry in the options menu, or HTML by language like { de, en }. Without info, there is no info entry.
view.center [52.51, 13.37628] The initial center as [lat, lng].
view.zoom 10 The initial zoom level.
view.minZoom 0 The minimal zoom level, it is raised to the highest minZoom of the maps. The maps can't be zoomed out further than the world fills the screen, so on large screens the lowest zoom level is higher, e.g. 4 for screens wider than 2048 pixels.
view.maxZoom 20 The maximal zoom level, it is lowered to the lowest maxZoom of the maps.
geolocate.maxZoom 18 The maximal zoom level when moving to the current location.
search.url https://nominatim.openstreetmap.org/search The url of a Nominatim search API.
search.maxZoom 18 The maximal zoom level when moving to a search result.
panes.maxLevel 3 How often panes can be split inside each other.
thumbnail '13/4400/2686' The tile (zoom/x/y) which is shown for each map in the map selection and the filmstrip.
tiles.transition 250 (OpenLayers' default) The duration in milliseconds in which the tiles fade in, 0 shows them as soon as they are loaded.
show all true, except filmstrip Which parts of the interface are shown, e.g. { grid: false }: the search, the buttons in the nav for zoom, geolocate, the grid, the crosshair and the map names (labels), and the options menu, the button of a pane which opens the modal to choose its map, and the filmstrip. The filmstrip is a scrollable strip with the thumbnails of all maps above the search and the buttons, e.g. for aerial images of different years. It changes the map of the active pane, which is the pane that was clicked or touched last. With panes.maxLevel: 0, splitting is disabled and there is only one pane. The thumbnails show the name of the maps, so short names like 2026 work best.
external OpenStreetMap, Google Maps, Google Earth The external maps in the options menu, which open the current view, like [{ name, url }]. {zoom}, {lat} and {lng} in the url are replaced, e.g. https://www.google.com/maps/@{lat},{lng},{zoom}z, urls without them get #map=zoom/lat/lng appended, like on openstreetmap.org. The url can also be a function, which gets the view as { zoom, lat, lng } and returns the url, e.g. for Google Earth, which needs a camera distance instead of a zoom level. The name can also be given by language like { de, en }, [] hides them. To add one to the defaults, use import { defaults } from '@jochenklar/maps' and external: [...defaults.external, { name, url }].
i18n English and German The texts of the interface by language, see src/config/i18n.js, e.g. { de: { search: 'Ortssuche' } } to change a single string or { fr: { … } } to add a language. The first language of the browser which has texts is used, otherwise English. Missing strings fall back to English, searchAttribution is HTML.
maps OpenStreetMap The maps, either as a flat array or in groups like [{ name, maps }], see below. The name of a group can also be given by language like { de, en }.

Each map in maps has a name, a tile url with {z}, {x} and {y} placeholders (and optionally {s} for the subdomains, 'abc' by default), the attribution as HTML, and optionally the minZoom and maxZoom of its tiles, which limit the zoom levels of the view, see view.minZoom and view.maxZoom.

Maps are identified in the url by the path of their tile url before the placeholders, or the hostname if there is no path, e.g. tile.openstreetmap.org or berlin/geoportal/luftbilder/2026-dop20rgb. These ids should be unique and only contain letters, numbers, _, -, ., ~ and /, otherwise a warning is shown in the console.

The public Nominatim instance may only be used lightly, see its usage policy. For sites with more traffic, set search.url to another instance.

Links

The url hash contains the layout of the panes and the view, e.g.

#panes=v(tile.openstreetmap.org,h(tile.opentopomap.org,tile.openstreetmap.org))&map=14/48.1370/11.5750
  • panes=id is a single pane showing the map with this id.
  • panes=v(a,b) is a pane split vertically (side by side), panes=h(a,b) one split horizontally (on top of each other), and a and b can be split again.
  • map=zoom/lat/lng is the view, like on openstreetmap.org.
  • show=grid,crosshair,labels lists the overlays which are shown: the coordinate grid, the center marker and the names of the maps. It is left out if none are shown.

Without a hash, the last layout and view are restored from the browser's local storage.

Development

Clone the repository and install the dependencies:

git clone git@github.com:jochenklar/maps
cd maps
npm install

The demo app for development is in demo/, which is set up like a project, but uses the component from src/ directly. npm run dev starts it with the config from demo/maps.config.js. Other commands:

npm run build    # build into demo/dist/
npm run preview  # serve the build
npm run lint     # run eslint

The same commands are available as make dev, make build, make lint and make preview. Checks for each commit are configured for pre-commit in .pre-commit-config.yaml.

Releasing

Releases are published to npm by the GitHub workflow in .github/workflows/publish.yml, when a release is published on GitHub. The version is taken from the tag of the release (e.g. v1.2.0 or 1.2.0), the version in package.json is only a placeholder. Releases marked as pre-release on GitHub are published with the next dist-tag.

About

A web app to compare tiled maps side by side.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages