V-Map

Provider-agnostische Web-Mapping-Komponentenbibliothek für Webanwendungen. Gebaut mit Stencil.js und OpenLayers, Cesium, Leaflet und Deck.gl als austauschbare Render-Provider.

Features

Provider-agnostisch: OpenLayers, Leaflet, Cesium und Deck.gl hinter einem einheitlichen deklarativen Web-Component-API — ein Providerwechsel ist eine einzige Prop (flavour).
Reicher Layer-Katalog: OSM, XYZ, WMS, WFS, WCS, GeoJSON, WKT, GeoTIFF, 3D-Tiles, Terrain, Deck.gl-Scatterplot, Google Tiles.
Layer-Gruppen & Layer-Control: Basemap-/Overlay-Verwaltung mit Sichtbarkeitssteuerung (v-map-layergroup, v-map-layercontrol).
Styling: v-map-style mit Unterstützung für GeoStyler JSON und SLD.
Deklaratives Building: v-map-builder zum Konfigurieren komplexer Karten per Attribut.
Runtime-Error-API: einheitliches vmap-error Event über alle Layer-Komponenten für konsistente Fehlerbehandlung.
Touch-optimiert: Desktop und mobile Geräte.
Vollständige TypeScript-Typen und JSX-Integration für Stencil/React/Vue/Svelte.

Installation

pnpm add @npm9912/v-map
# oder
npm install @npm9912/v-map

Je nach gewünschtem Provider installierst du zusätzlich die passende Peer-Dependency:

pnpm add ol            # für flavour="ol"
pnpm add leaflet       # für flavour="leaflet"
pnpm add cesium        # für flavour="cesium"
pnpm add @deck.gl/core # für flavour="deck"

Verwendung

Plain HTML / ESM

<!DOCTYPE html>
<html>
<head>
  <script type="module"
          src="./node_modules/@npm9912/v-map/dist/v-map/v-map.esm.js"></script>
  <style>v-map { display: block; width: 100%; height: 100vh; }</style>
</head>
<body>
  <v-map flavour="ol">
    <v-map-layergroup group-title="Basiskarten" basemapid="OSM-BASE">
      <v-map-layer-osm id="OSM-BASE" label="OpenStreetMap"
                       z-index="0" opacity="1.0"></v-map-layer-osm>
    </v-map-layergroup>
    <v-map-layergroup group-title="Overlays">
      <v-map-layer-geojson src="data/points.geojson"></v-map-layer-geojson>
    </v-map-layergroup>
  </v-map>
</body>
</html>

Framework-Integration (React, Vue, Svelte, SvelteKit …)

import { defineCustomElements } from '@npm9912/v-map/loader';

defineCustomElements();

Danach stehen die Custom Elements (<v-map>, <v-map-layer-osm>, …) im gesamten Projekt zur Verfügung.

Eine vollständige SvelteKit-Integration findest du unter examples/sveltekit/.

Unterstützte `flavour`-Werte

Wert	Render-Provider
`ol`	OpenLayers (Default)
`leaflet`	Leaflet
`cesium`	CesiumJS (2D + 3D Globus)
`deck`	Deck.gl (GPU-beschleunigt)

Komponenten-Übersicht

Insgesamt 19 Web Components in src/components/:

Karten-Container & Infrastruktur

v-map — Haupt-Kartencontainer
v-map-builder — deklaratives Building komplexer Karten
v-map-layergroup — Gruppierung und Sichtbarkeitssteuerung
v-map-layercontrol — interaktives Layer-Control
v-map-style — Styling via GeoStyler JSON oder SLD
v-map-error — deklarative Fehler-Toasts ohne JavaScript

Raster-Layer

v-map-layer-osm — OpenStreetMap-Tiles
v-map-layer-xyz — generische XYZ-Tile-Sources
v-map-layer-google — Google Maps Tiles
v-map-layer-wms — OGC WMS
v-map-layer-wcs — OGC WCS
v-map-layer-geotiff — GeoTIFF

Vektor-Layer

v-map-layer-geojson — GeoJSON
v-map-layer-wkt — Well-Known-Text
v-map-layer-wfs — OGC WFS
v-map-layer-scatterplot — Deck.gl-Scatterplot

3D & Terrain

v-map-layer-tile3d — 3D Tiles (Cesium)
v-map-layer-terrain — Terrain-Provider
v-map-layer-terrain-geotiff — Terrain aus GeoTIFF

Vollständige API-Referenz: GitHub Pages Dokumentation.

Error Handling

Alle Layer-Komponenten emittieren ein einheitliches vmap-error Event bei Lade- und Laufzeitfehlern.

Deklarativ über <v-map-error> (kein JavaScript nötig):

<v-map flavour="ol">
  <v-map-error position="top-right" auto-dismiss="5000"></v-map-error>
  <!-- ... layer ... -->
</v-map>

Programmatisch:

document.querySelector('v-map')?.addEventListener('vmap-error', (e) => {
  const { detail } = e as CustomEvent;
  console.error(detail.type, detail.message);
});

Details: Error-Handling Guide.

Entwicklung

Voraussetzungen

Node.js ≥ 22
pnpm ≥ 9
optional: Docker (für den Devcontainer)

Setup

pnpm install
pnpm start          # Dev-Server auf http://localhost:3333

Tests

Das Projekt nutzt Vitest mit den Projekten spec, unit und browser.

pnpm test                       # spec + browser
pnpm test:coverage              # alle Vitest-Projekte mit Coverage
pnpm test:vitest:browser        # nur Browser-/Runtime-Tests
pnpm test:vitest:browser:watch  # Browser-Tests im Watch-Modus

Hintergrund und CI-Hinweise: docs/dev/vitest.md.

Storybook

pnpm storybook     # http://localhost:6006

Dokumentation lokal bauen

pnpm docs:dev      # VitePress Dev-Server
pnpm docs:build    # Statische Ausgabe in docs/.vitepress/dist

Devcontainer

Das Projekt enthält eine vorkonfigurierte Devcontainer-Umgebung (.devcontainer/):

Basis-Image node:22
pnpm, GitHub CLI, ESLint, Prettier, Vitest vorinstalliert
Automatisches Setup via post-create.sh

Öffne das Repo in VS Code Dev Containers oder GitHub Codespaces.

Build & Release

Build

pnpm build

Erzeugt die distributierbaren Bundles in dist/ sowie den loader/ für Framework-Integration.

Release

Releases werden vollautomatisch durch semantic-release erstellt. Ausgelöst wird der Release-Workflow durch einen Merge von develop nach main.

Versionierung und Changelog entstehen aus den Conventional Commits seit dem letzten Tag.
npm-Publish, GitHub-Release und Tag werden automatisch erzeugt.
Vollständige Anleitung, Voraussetzungen und Fehlerbehebung: docs/releasing.md.

Projektstruktur

v-map/
├── src/
│   ├── components/          # 19 Web Components (v-map, v-map-layer-*, …)
│   ├── map-provider/        # Provider-Implementierungen (ol, leaflet, cesium, deck)
│   ├── testing/             # Test-Setups und Mocks
│   └── index.ts             # Entry Point
├── loader/                  # Framework-Loader (defineCustomElements)
├── dist/                    # Build-Artefakte (generiert)
├── docs/
│   ├── releasing.md         # Release-Prozess
│   ├── dev/                 # Interne Entwicklerdoku
│   └── .vitepress/          # VitePress-Konfiguration
├── demo/                    # HTML- und SvelteKit-Integrationsdemos
├── .devcontainer/           # VS Code / Codespaces Setup
├── .github/workflows/       # CI/CD Pipelines (test, test-browser, build, release, docs)
├── .releaserc.json          # semantic-release Konfiguration
├── stencil.config.ts        # Stencil-Konfiguration
├── vite.config.ts           # Vite-Konfiguration
└── vitest.config.mts        # Vitest-Projekte

Architektur

Saubere Trennung von deklarativem DOM-API (Web Components) und imperativer Kartenlogik (Provider).
Engine-agnostisch: Austausch bzw. Koexistenz von OpenLayers, Leaflet, Deck.gl und Cesium über ein klares Interface.
Typsicherheit durch LayerConfig-Union mit exhaustiveness checks.
Shadow-DOM-kompatibel: CSS-Injection, Adopted Stylesheets.
Erweiterbarkeit: Neue Layer-Typen und Engines fügen sich je über einen Adapter ein.
Wiederverwendbarkeit: VMapLayerHelper als einheitliche Registrierungs-/Update-Pipeline.
Konsistentes Error-API: einheitliches vmap-error Event über alle Layer-Komponenten.

Contributing

Pull Requests und Issues sind willkommen.

Branch-Strategie: Feature-Branch → develop → main (siehe docs/releasing.md)
Commit-Format: Conventional Commits
Alle Tests und Lints müssen grün sein (pnpm test, pnpm lint, pnpm typecheck)

Lizenz

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 445 Commits
.devcontainer		.devcontainer
.github		.github
.storybook		.storybook
config		config
demo		demo
docs		docs
examples		examples
public		public
scripts		scripts
src		src
types		types
.editorconfig		.editorconfig
.gitignore		.gitignore
.huskyrc		.huskyrc
.lintstagedrc		.lintstagedrc
.prettierrc.json		.prettierrc.json
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
stencil-readme.md		stencil-readme.md
stencil.config.ts		stencil.config.ts
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json
vite.config.ts		vite.config.ts
vitest.config.mts		vitest.config.mts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

V-Map

Features

Installation

Verwendung

Plain HTML / ESM

Framework-Integration (React, Vue, Svelte, SvelteKit …)

Unterstützte `flavour`-Werte

Komponenten-Übersicht

Error Handling

Entwicklung

Voraussetzungen

Setup

Tests

Storybook

Dokumentation lokal bauen

Devcontainer

Build & Release

Build

Release

Projektstruktur

Architektur

Contributing

Lizenz

About

Uh oh!

Releases 14

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

V-Map

Features

Installation

Verwendung

Plain HTML / ESM

Framework-Integration (React, Vue, Svelte, SvelteKit …)

Unterstützte flavour-Werte

Komponenten-Übersicht

Error Handling

Entwicklung

Voraussetzungen

Setup

Tests

Storybook

Dokumentation lokal bauen

Devcontainer

Build & Release

Build

Release

Projektstruktur

Architektur

Contributing

Lizenz

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 14

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Unterstützte `flavour`-Werte

Packages