Overview

Sphyra is a self-hosted OpenStreetMap stack for Armenia. @sphyra/react-native wraps the same REST API as @sphyra/js with React Native primitives: a ready-made <SphyraMap>, declarative markers, geocoding hooks, and Phase-10 map controls.

What you get out of the box

• SphyraProvider + useSphyra() — shared client context
• <SphyraMap> — signed style, day/dusk/night presets, 2D/3D switching
• <SphyraMarker> / <SphyraPopup> — declarative map overlays
• useReverseGeocode, useForwardGeocode, useTileConfig — debounced data hooks
• Full TypeScript types in dist/index.d.ts

Runnable reference: examples/expo-demo/ — Expo dev-client demo with full parity to the web demo.

Prerequisites

cd sphyra/api
docker compose up -d
curl http://localhost:4000/health   # → {"status":"ok"}

The dev key sphyra_dev_local is seeded automatically. Never commit a production key.

Environments

| Environment | baseUrl | apiKey | Notes | |-------------|-----------|----------|-------| | Local simulator | http://localhost:4000 | sphyra_dev_local | Works on iOS Simulator / Android emulator | | Physical device | http://<your-lan-ip>:4000 | sphyra_dev_local | Replace localhost — the device cannot reach your laptop's loopback | | Production | https://sphyra.kidup.am | SPHYRA_API_KEY | From your secret store |

Install

pnpm add @sphyra/react-native @maplibre/maplibre-react-native

| Package | Role | |---------|------| | @maplibre/maplibre-react-native ^10.0.0 | Required peer — map rendering | | react, react-native | Provided by your host app |

Complete native setup per the MapLibre React Native guide before running on device.

Setup

Wrap your app (or map screen) in SphyraProvider:

import { SphyraClient, SphyraProvider } from "@sphyra/react-native";

const client = new SphyraClient({
  baseUrl: "http://localhost:4000",
  apiKey: "sphyra_dev_local",
});

export default function App() {
  return (
    <SphyraProvider client={client}>
      <YourMapScreen />
    </SphyraProvider>
  );
}

Map

<SphyraMap> reads the client from context, fetches the signed style once, and switches presets/modes locally — no style re-fetch.

import { View, Image, StyleSheet } from "react-native";
import { SphyraMap, SphyraMarker } from "@sphyra/react-native";

function MapScreen() {
  return (
    <View style={styles.fill}>
      <SphyraMap
        preset="day"
        mode="3d"
        center={[44.5152, 40.1872]}
        zoom={13}
        style={styles.fill}
        onError={(err) => console.warn(err.code, err.message)}
      >
        <SphyraMarker
          id="republic-square"
          coordinate={[44.5152, 40.1872]}
          onPress={() => console.log("marker pressed")}
        >
          <Image source={require("./pin.png")} style={{ width: 32, height: 32 }} />
        </SphyraMarker>
      </SphyraMap>
    </View>
  );
}

const styles = StyleSheet.create({ fill: { flex: 1 } });

Use when you need raw signed URLs instead of <SphyraMap>. Auto-refreshes five minutes before expiry.

import { useSphyra, useTileConfig } from "@sphyra/react-native";

function TileConfigPanel() {
  const client = useSphyra();
  const { data, loading, error } = useTileConfig(client);

  if (loading) return null;
  if (error) return null;
  // data.styleUrl · data.tileUrl · data.expiresAt
  return null;
}

1.2.0 — Mapbox Standard look

The style this SDK renders was rebuilt for Mapbox Standard parity (S-1.0.0-11-023). What changed for consumers:

• New layer ids. Buildings are now a stack — buildings-ao, buildings-ao-contact (ground shadows), buildings-3d (walls) and buildings-3d-roof (roof-edge contour). If you toggle layers by id, use metadata["sphyra:layerGroups"] instead of hard-coded lists.

• POIs draw above the buildings so a building never covers the labels in front of it. applyStyleVariant() (which calls apply3dGroundDepth()) keep that order; call them after adding your own layers if you insert into the middle of the stack.

• Preset colours look wrong in isolation and right on screen — they are fitted through MapLibre's extrusion lighting (see the Map-Style-Standard documentation page). Change them through the preset table, not by editing layer paint.

• Zoom ranges match the tile server: buildings and POIs come from z18 tiles and MapLibre overzooms above. Asking for z19+ tiles used to 404 and buildings vanished while zooming.

• The sky and the globe are web-only, and this SDK strips them. The style carries a sky per preset and a projection (globe when zoomed out) for MapLibre GL JS 5; MapLibre Native implements neither, so applyStyleVariant() deletes sky, projection and the legacy fog before the style reaches the native renderer — otherwise they would only produce warnings on every load. Mobile keeps the mercator map with a plain sky. Closing that gap is the MapLibre Native engine upgrade, not this release (ADR-008).

• Set minZoom if your map can be pinched all the way out. Because there is no globe to hand the low zooms to, MapLibre Native keeps drawing the mercator plane and repeats it sideways once the viewport is wider than the world — 512 * 2^zoom dp, so from about z1.5 on a 13" tablet in landscape, z0.9 on a phone in landscape. The result reads as several copies of the world side by side. <SphyraMap minZoom={3}> puts the floor a continent-wide view above that threshold; the matching maxZoom caps the other end. Both bound gestures and imperative setCamera().

• minZoom alone is half the job — pair it with maxBounds. The zoom floor stops the world repeating sideways; it does nothing about running off the top. MapLibre paints background across the whole viewport but has no geometry past ~85.05°, so panning over the pole fills the rest of the screen with a slab of the ground colour. MapLibre fences the camera centre, not the viewport (on Android maxBounds is setLatLngBoundsForCameraTarget), so the fence belongs half a viewport below the pole — which is what worldPanBounds(minZoom, viewportHeightDp) returns:

  import { SphyraMap, worldPanBounds } from "@sphyra/react-native";
  
  const BOUNDS = worldPanBounds(3, Dimensions.get("window").height);
  
  <SphyraMap minZoom={3} maxZoom={18} maxBounds={BOUNDS} />;

  The SDK never applies one on its own: only the consumer knows how tall the map is laid out.

• Tiles are served gzipped and cacheable; a viewport is roughly half the bytes it was.

Geocoding

Reverse — useReverseGeocode(client, params)

Takes client as the first argument. Pass null to stay idle. Debounced 500 ms.

import { useSphyra, useReverseGeocode } from "@sphyra/react-native";
import { Text } from "react-native";

function ReverseExample() {
  const client = useSphyra();
  const { data, loading, error } = useReverseGeocode(client, {
    lat: 40.1872,
    lon: 44.5152,
    lang: "hy",
  });

  if (loading) return <Text>Loading…</Text>;
  if (error) return <Text>{error.code}: {error.message}</Text>;
  return <Text>{data?.displayName ?? "—"}</Text>;
  // → "Հանրապետության հրապարակ, Երևան, Հայաստան"
}

Forward — useForwardGeocode({ query, lang, … })

Reads the client from SphyraProvider context — no client argument. Debounced; queries when trimmed length ≥ 2.

import { useForwardGeocode } from "@sphyra/react-native";
import { Text } from "react-native";

function SearchExample() {
  const { results, loading, error } = useForwardGeocode({
    query: "Աբովյան",
    lang: "hy",
    limit: 5,
  });

  if (loading) return <Text>Searching…</Text>;
  if (error) return <Text>{error.code}: {error.message}</Text>;

  return (
    <>
      {results.map((r, i) => (
        <Text key={i}>{r.displayName}</Text>
      ))}
    </>
  );
}

Hook signatures differ by design — do not pass client to useForwardGeocode; do pass it to useReverseGeocode and useTileConfig.

Error handling

| Source | How errors appear | |--------|-------------------| | Hooks | error: SphyraError \| null on hook state (.code, .statusCode, .message) | | Client methods | Thrown SphyraError — use try/catch + instanceof SphyraError |

Retry policy (same as @sphyra/js): 5xx / TIMEOUT / NETWORK retry 3× at 1s / 2s / 4s; 4xx fail immediately; default timeout 10 000 ms (timeout on SphyraClient).

Runnable demo

examples/expo-demo/ mirrors the @sphyra/js web demo: map presets, Phase-10 services, interactive directions, and search — built with Expo dev client.

See the demo's own README for LAN-IP setup and run commands.

TypeScript

All public types ship in dist/index.d.ts:

| Type | Purpose | |------|---------| | SphyraClientOptions | Client constructor | | SphyraMapProps / SphyraMarkerProps | Map components | | ReverseGeocodeState | useReverseGeocode return shape | | ForwardGeocodeState | useForwardGeocode return shape | | TileConfigState | useTileConfig return shape | | GeocodeLang | "hy" | "en" | "ru" |

pnpm typecheck

Commit hygiene

This repository must show only its human authors in the contributor list. A local hook rejects AI co-author trailers before a commit is created — enable it once per clone:

git config core.hooksPath .githooks

The same check runs in CI (no-ai-trailers) over every commit in a merge/pull request range, so a bypassed local hook still fails the pipeline.