Skip to content

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.js enables unstable_transformImportMeta for web only, mapping import.meta.url to the bundle URL. Without it the whole web bundle fails to parse.
  • metro.config.js copies maplibre-gl/dist/maplibre-gl-worker.mjs to public/maplibre-gl-worker.js each time Metro starts, so the dev server and expo export both serve it. The .js name gets a JavaScript MIME type from nginx, which has no .mjs mapping. The copy is gitignored.
  • engine/maplibre.ts calls setWorkerUrl('/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

  1. Extend the MapMarker union in MapView.tsx.
  2. Add a web case in engine/markers/index.tsx (HTML primitives).
  3. Add a native case in native/MarkerOverlay.tsx (RN primitives).
  4. Add styling for both. Reuse MARKER_COLORS + getEventIcon / getLocationIcon from components/ui/categoryIcons.ts for 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 MapMarker schema 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.