@facilitronworks/react-native-windows-maps

The app-agnostic half of a react-native-windows map surface: Web Mercator projection maths, and a builder for the maplibre-gl HTML page that renders inside a WebView2 island.

Zero runtime dependencies. Both modules are pure TypeScript with no imports.

What this is not

This package deliberately does not ship a <MapView> component or any basemap style resolution.

Style resolution reads EXPO_PUBLIC_* environment variables, and babel-preset-expo only inlines those for files outside node_modules. A resolver living in this package would silently read '' in every build: the map would fall back to raw OSM tiles and the dark-mode toggle would inject a byte-identical style, doing nothing, with no error and no failing test. The host app owns styling and passes the resolved style in.

Usage

import {
  buildMapPage,
  projectToViewport,
  regionToZoom,
  viewportToRegion,
  type LatLng,
  type Region,
} from '@facilitronworks/react-native-windows-maps';

buildMapPage(options) returns a complete HTML document. Render it in a WebView that injects window.ReactNativeWebView.postMessage before content load.

Bridge protocol

page → host, via window.ReactNativeWebView.postMessage:

| message | meaning | | --- | --- | | {type:'ready'} | maplibre constructed, first style loaded | | {type:'viewport', center, zoom, css} | on every move and on resize | | {type:'press', coordinate} | single click on the map surface | | {type:'markerPress', id} | an in-page marker element was clicked | | {type:'error', message} | script / style / tile failure |

host → page, via injectJavaScript against window.__worksMap:

| call | meaning | | --- | --- | | setRegion({center, zoom}, durationMs) | camera move (0 = jump) | | setStyle(styleJsonOrUrl) | appearance change | | setMarkers(list) | replace the in-page marker layer |

Markers render in the page, not over it

On react-native-windows the WebView2 island composites above all react-native content within its bounds, regardless of sibling order or zIndex (verified against three independent layering strategies). An RN overlay can therefore never be seen. The host still computes clusters and owns every handler; the page only draws the bubbles it is handed via setMarkers and reports presses back. Each entry is plain data — {id, latitude, longitude, kind:'cluster'|'pin', label, bg, fg, border, size} — themed by the host.

maplibre-gl is pinned by version and SRI

The page loads maplibre-gl from unpkg pinned by version and by sha384 subresource integrity. MAPLIBRE_JS_SRI / MAPLIBRE_CSS_SRI are the hashes of the exact artifacts in [email protected]. A tampered or substituted file fails the check, the script does not execute, and the page reports {type:'error'} so the host can fall back.

maplibre-gl is declared as an optional peer dependency so a host on a different version gets an install-time signal. If you bump it, the two SRI constants must be regenerated in the same change or the map loads nothing.

Platform

Correct only under the windows platform, where Metro redirects react-native to react-native-windows.

License

MIT