map0

A modern, embeddable, JSON-configurable web map client built on MapLibre GL JS. One script tag + one JSON config = a full-featured map on any web page.

map0.net: website and live demos.

Status: approaching the M1 milestone. Layer tree, WMS/WMTS/WFS/OGC API Features, vector tiles, GeoJSON/GeoParquet/COG, feature info, legends, search, measuring, print, permalink, theming and i18n all work against live services. Published as an early preview (map0-viewer 0.3.0 on npm, MIT); the API and the config format are still drafts and will change without a deprecation path until 1.0. See 07-roadmap.md and the CHANGELOG.

The idea in one paragraph

map0 adds a configurable interface to MapLibre: basemaps, a layer tree, legends, feature popups, search, measuring, print and globe view. A JSON document defines the map, its appearance and its tools. Store it as a file or in a CMS field, then embed the viewer as a web component in your page.

<script type="module" src="map0.js"></script>
<map0-viewer config-src="my-map.map0.json" style="height:520px"></map0-viewer>

Using it in a page

For self-hosting, copy node_modules/map0-viewer/dist/ next to your page:

npm install map0-viewer   # prebuilt bundle with MapLibre included

…or straight from a CDN, nothing to install:

<script type="module" src="https://cdn.jsdelivr.net/npm/map0-viewer@0.3.0/dist/map0.js"></script>

See packages/map0/README.md for the whole integration, and docs/09-engineering-notes.md for how the package is released.

Working on map0

Prerequisites: Node ≥ 22 and pnpm (enable it with corepack enable; the version is pinned via packageManager).

pnpm install
pnpm dev

Then open the demo gallery. Each demo includes an interactive map, an explanation and its configuration. Most use public services; others use local data files:

Group	Demos
Data sources	WMS · WMTS · WFS · OGC API Features · Vector tiles · GeoJSON & clustering · GeoParquet · Cloud Optimized GeoTIFF
Map features	Popups & hover · Legend · Search · Measure · Coordinates · Print & export · Add layers · Share & permalink · Globe
Configuration	Minimal config · Theming · Languages · Config inheritance · Validate a config
Integration	Script tag embed (built bundle; run pnpm demo:standalone first) · Lazy loading

More commands:

pnpm test                       # unit tests (Vitest)
pnpm typecheck                  # strict TypeScript project build
pnpm build                      # library bundle → packages/ui/dist/
pnpm demo:standalone            # build + copy the bundle for the standalone demo page
pnpm release                    # version, changelog, npm publish, GitHub release (docs/09 §release)
node e2e/verify-demos.mjs       # headless smoke run over every demo, with screenshots
node e2e/verify-demos.mjs wms   # …or just one (dev server must be running)

Repository layout

packages/schema   config types, validation (JSON-path errors), defaults, published JSON Schema (v1.json)
packages/core     headless engine: basemap manager, source adapters, feature info, i18n
packages/ui       the <map0-viewer> web component (Lit) + panels, popups, theming
site/              landing page, /demos gallery and demo pages (EN, with /de/ built from
                   per-page catalogues in site/i18n/)
site/public/       demo configs and data served as-is
e2e/              headless smoke verification (grows into the Playwright suite in M1)
docs/             specification

Distribution note: packages/ui/dist/ is a flat folder containing map0.js, its chunks and MapLibre's three files shipped verbatim. Deploy the folder as a unit; the embed stays one script tag. A page loads ~34 KB gzip for the element itself; the engine and MapLibre (~316 KB) load when the map approaches the viewport, and capabilities parsing, proj4, PMTiles, the COG decoder, measuring and the dialogs only when those features are used. pnpm size prints the breakdown and fails when the page tier grows.

Documents

Doc	Content
01-vision.md	Problem, vision, target users, design principles, non-goals, positioning
02-landscape.md	Prior-art research, comparison table, gap analysis, engine choice (MapLibre vs OL vs deck.gl)
03-requirements.md	Functional & non-functional requirements (MoSCoW)
04-configuration.md	The heart: config philosophy + full annotated JSON example
05-maplibre-capabilities.md	MapLibre v6 capability map, build-vs-reuse matrix, field notes from M0
06-architecture.md	Technical architecture (packaging, layering, adapters, security)
07-roadmap.md	Status: what is done, what is left, milestones M0 → M2
08-decisions.md	Decision log D-01…D-05 + open items
09-engineering-notes.md	Invariants, field notes on MapLibre and real SDI services, debugging playbook
10-review-fixes.md	External review findings, verdicts and what was changed in response

Conventions

• All project documentation and code in English.
• Config examples target live Austrian SDI services (basemap.at, Stadt Wien OGD) where possible; placeholder *.example.gv.at URLs mark illustrative endpoints.
• A config key without documentation is not done; schema changes update 04-configuration.md in the same change.

Licence

MIT; see LICENSE. The published bundle contains third-party code (MapLibre GL JS verbatim, others compiled in); their licences are reproduced in packages/map0/THIRD-PARTY-NOTICES.md, regenerated on every pnpm build:npm.

---

Made with ❤️ by Spatial Focus