Maps¶
Tomoda renders maps through the MapLibre rendering stack. The same shared types and marker spec drive both surfaces, but each platform uses its native renderer:
| Platform | Renderer | Package |
|---|---|---|
| Web | MapLibre GL JS | maplibre-gl |
| iOS / Android | MapLibre Native (Metal / OpenGL ES) | @maplibre/maplibre-react-native |
No WebView. No JS bridge for tile rendering. Markers on native are real React Native views composited by the platform.
Where the code lives¶
| Path | Role |
|---|---|
frontend/components/map/MapView.tsx |
Shared types: MapMarker, MapRegion, MapControls, MapViewProps. |
frontend/components/map/MapView.web.tsx |
Web shim. Mounts <MapEngine> inline. |
frontend/components/map/MapView.native.tsx |
Native shim. Wraps @maplibre/maplibre-react-native <Map> + <Marker> per marker. |
frontend/components/map/engine/MapEngine.tsx |
Web-only MapLibre GL JS wrapper. Owns the JS map instance, marker DOM diff loop, style swap, event emission. |
frontend/components/map/engine/maplibre.ts |
Web entry for maplibre-gl. Every web map imports it from here so the worker URL is set first. |
frontend/components/map/engine/styles.ts |
Shared basemap styles (vector style URLs + a label-free land/water style, light/dark). |
frontend/components/map/engine/markers/ |
Web-only HTML marker components (divs + CSS for hover/glass-card expansion). |
frontend/components/map/native/MarkerOverlay.tsx |
Native marker components (RN primitives: View, Image, Text, react-native-svg). |
frontend/components/map/MapAttribution.tsx |
Shared compact ⓘ pill (hidden by default; tap/hover reveals the basemap credits). |
Tiles¶
Both platforms render vector tiles (OpenMapTiles schema) from the public instance at tiles.openfreemap.org. No API key, no registration, no request limits. Light + dark variants are selected via the mapTheme prop:
| Export | Used by | Light | Dark |
|---|---|---|---|
STYLES |
Discover map, location picker, region choropleth | https://tiles.openfreemap.org/styles/positron |
https://tiles.openfreemap.org/styles/dark |
STYLES_NOLABELS |
World choropleth | Inline style: background + water fill only |
Same, dark colours |
STYLES entries are style URLs; both renderers fetch the style JSON, glyphs and sprites themselves. STYLES_NOLABELS is an inline style object so the schematic atlas skips glyph and sprite fetches entirely.
Choropleth fills are added on top of the basemap, so in RegionChoropleth the basemap labels sit under the fill (same as the earlier raster basemap).
Attribution is required (OpenFreeMap, © OpenMapTiles, © OpenStreetMap, each linked). The built-in MapLibre attribution control is disabled on every map, so the credit lives in MapAttribution.tsx (mounted by the Discover map and the location pickers).
To self-host or swap providers, edit engine/styles.ts. Both renderers accept the same value (style URL or StyleSpecification).
Web bundling¶
maplibre-gl v6 is ESM-only and loads its tile worker as a separate file it finds through import.meta.url. Metro's web bundle is a classic script, so three pieces make that work:
babel.config.jsenablesunstable_transformImportMetafor web only, mappingimport.meta.urlto the bundle URL. Without it the whole web bundle fails to parse.metro.config.jscopiesmaplibre-gl/dist/maplibre-gl-worker.mjstopublic/maplibre-gl-worker.jseach time Metro starts, so the dev server andexpo exportboth serve it. The.jsname gets a JavaScript MIME type from nginx, which has no.mjsmapping. The copy is gitignored.engine/maplibre.tscallssetWorkerUrl('/maplibre-gl-worker.js?v=<version>'). The query busts caches on upgrade.
maplibre-gl and the native SDK ship different style-spec versions whose StyleSpecification types don't cross-assign, so engine/styles.ts declares its own type for the inline land/water style and checks it against both.
Marker API¶
Callsites pass a flat markers: MapMarker[] array. The union is discriminated by type:
| Variant | Visual |
|---|---|
pin |
Generic single-point pin. Used by LocationPicker. |
user |
Current user's avatar tile. |
friend |
Friend avatar tile with optional online/active status dots. |
cluster |
Stacked-avatar cluster bubble with count. |
discovery |
Unified marker for event, location, moment, geo_cluster sub-kinds. |
onMarkerPress(id) fires when any marker is tapped. Marker ids are caller-controlled.
Adding a new marker variant¶
- Extend the
MapMarkerunion inMapView.tsx. - Add a web case in
engine/markers/index.tsx(HTML primitives). - Add a native case in
native/MarkerOverlay.tsx(RN primitives). - Add styling for both. Reuse
MARKER_COLORS+getEventIcon/getLocationIconfromcomponents/ui/categoryIcons.tsfor visual consistency.
Map controls¶
onMapReady receives MapControls once the map loads:
| Method | Web | Native |
|---|---|---|
zoomIn() / zoomOut() |
map.zoomIn() / map.zoomOut() |
cameraRef.zoomTo(zoom ± 1) |
animateTo(lat, lng, zoom?) |
map.flyTo |
cameraRef.flyTo |
panTo(lat, lng, padding?) |
map.easeTo({ padding }) |
cameraRef.easeTo({ padding }) |
canZoomIn() / canZoomOut() |
Compare with getMaxZoom / getMinZoom |
Always returns true |
panTo is the right call when a UI panel covers part of the viewport — the padding rect tells the map which area to centre within.
Why this stack¶
- No WebView on native — tile rendering, gestures, and marker compositing all run on the GPU via Metal / OpenGL ES. Pan and zoom stay smooth even with hundreds of markers in view.
- Same
MapMarkerschema on both platforms — adding a marker kind is a coordinated change but the data model + visual spec live in one place. - No tile-server infra. The public vector tile instance is free; self-hosting the same OpenMapTiles schema only changes
engine/styles.ts.