plugingsMap3D — the official plugins for map3D

Real data poured into a React 3D map: French BDTOPO building attributes on pick, live public webcams around the view.

Live demo ↗ · map3D library ↗ · Plugin API 🇬🇧 · Documentation 🇫🇷 · Changelog

---

Why this repository

map3D is a real-time 3D mapping library for React. It knows about no business data source — that is what plugins are for. This monorepo holds the official ones, published under the @pasquelin scope: 1 plugin = 1 package (packages/<name>/) + its runnable example (packages/<name>/example/).

A plugin plugs into one of the three lanes of the definePlugin contract:

Lane	What it does	Example here
enrich	completes a map object after an interaction (building pick)	geopf
markers	supplies DOM markers from a remote source, refreshed on view change	windy
layer	reaches engine.scene / engine.projection directly to draw its own 3D	plan-3d

The plugins

Package	Lane	Role	npm
@pasquelin/map3d-plugin-geopf	enrich	French buildings: clicking a 3D building resolves its official BDTOPO attributes from the IGN Géoplateforme (nature, use, height, floors, materials…) through useBuildingEnrichment(). The pick stays instant; enrichment runs in the background.
@pasquelin/map3d-plugin-windy	markers	Real public webcams around the current view (Windy Webcams API v3): one marker per webcam, thumbnail as avatar, preview tooltip and a menu (open / copy link).
@pasquelin/map3d-plugin-plan-3d	layer	Placeholder for the layer lane: drops a reference volume, reprojected every frame. It demonstrates the contract, it is not a product.	private
@pasquelin/map3d-plugin-template	—	Starter to copy when writing your own plugin.	private

The two publishable packages share a single version: one vX.Y.Z tag publishes them together.

Installation

npm i @pasquelin/map3d @pasquelin/map3d-plugin-geopf
# or: pnpm add … / yarn add …

react, react-dom (19), three (≥ 0.169) and @pasquelin/map3d (^0.2.0) are peerDependencies — never bundled by the plugins.

Quick start

A plugin is passed to <Map>; it is disabled by default and switched on from map3D's plugin hub (Settings menu).

import { Map } from '@pasquelin/map3d'
import { geopfBatiments } from '@pasquelin/map3d-plugin-geopf'
import { windyWebcams } from '@pasquelin/map3d-plugin-windy'

<Map plugins={[geopfBatiments(), windyWebcams({ apiKey: import.meta.env.VITE_WINDY_API_KEY })]} />

Reading the geopf enrichment from a child of <Map>:

import { useBuildingEnrichment } from '@pasquelin/map3d'

function BuildingInfo() {
  const enrichment = useBuildingEnrichment()
  return <pre>{JSON.stringify(enrichment, null, 2)}</pre>
}

Every package has its own detailed README (options, API key safety, limits) and its example:

pnpm --filter @pasquelin/map3d-plugin-geopf-example dev
pnpm --filter @pasquelin/map3d-plugin-windy-example dev

Writing your own plugin

cp -r packages/plugin-template packages/my-plugin
# rename `name` and `meta.id`, adjust `config` and the lane it uses
pnpm install && pnpm validater

The plugin contract (definePlugin, the enrich / markers / layer lanes) is documented on the map3D side. To propose an official plugin here, see CONTRIBUTING.md.

Development

pnpm monorepo (Node 22). Prerequisite: pnpm install.

Command	Effect
pnpm build	library build for each package (dist/: ESM + CJS + .d.ts)
pnpm typecheck	tsc --noEmit per package
pnpm test	Vitest (colocated *.test.ts)
pnpm lint / pnpm format	ESLint / Prettier
pnpm validater	typecheck + lint + format:check + test — the full gate, replayed in CI
pnpm version:plugins X.Y.Z	unified bump (root + geopf + windy)

Source, comments and internal documentation are written in French. any is forbidden (strict + noUncheckedIndexedAccess), type rather than interface.

Publishing

Automatic through GitHub Actions: pushing a vX.Y.Z tag publishes the publishable packages to npm with signed provenance over OIDC (npm Trusted Publishing — no token). The flow is detailed in CLAUDE.md.

Contributing

Features start from develop and return to it through a PR (main is the release branch). One feature = one branch = one isolated worktree. Read CONTRIBUTING.md, the code of conduct and the security policy.

Licence

MIT © Alban Pasquelin — see LICENSE. Note: the map3D library itself is licensed under PolyForm Noncommercial.