react-native-better-maps
/react-native-better-maps
Expert guide to react-native-better-maps — native maps for React Native built on Nitro Modules, with Apple MapKit and Google Maps provider adapters, descriptor-based overlays, and native marker clustering. Use when installing or configuring the map, rendering markers or overlays, driving the camera, diagnosing lag or marker re-render churn, working around a provider or platform difference, migrating from react-native-maps, or changing the library's TypeScript, Swift, Kotlin, or Nitro specs.
- Author
- gmi-software ↗
- Repository
- better-skills ↗
- Licence
- MIT
- Last repository change
- 14.10.2026
Assessment and security
- Files in this package
- 12
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Expert guide to react-native-better-maps — native maps for React Native built on Nitro Modules, with Apple MapKit and Google Maps provider adapters, descriptor-based overlays, and native marker clustering. Use when installing or configuring the map, rendering markers or overlays, driving the camera, diagnosing lag or marker re-render churn, working around a provider or platform difference, migrating from react-native-maps, or changing the library's TypeScript, Swift, Kotlin, or Nitro specs.
Original author description
Expert guide to react-native-better-maps — native maps for React Native built on Nitro Modules, with Apple MapKit and Google Maps provider adapters, descriptor-based overlays, and native marker clustering. Use when installing or configuring the map, rendering markers or overlays, driving the camera, diagnosing lag or marker re-render churn, working around a provider or platform difference, migrating from react-native-maps, or changing the library's TypeScript, Swift, Kotlin, or Nitro specs.
How it works
- Version verification
- When to use
- When NOT to use
- Core architecture
- API guidance
- Problem → reference routing
- Canonical performance workflow
- Common mistakes
- Troubleshooting
- Known limitations (high signal)
SKILL.md preview
---
name: react-native-better-maps
description: >-
Expert guide to react-native-better-maps — native maps for React Native built on Nitro
Modules, with Apple MapKit and Google Maps provider adapters, descriptor-based overlays,
and native marker clustering. Use when installing or configuring the map, rendering
markers or overlays, driving the camera, diagnosing lag or marker re-render churn,
working around a provider or platform difference, migrating from react-native-maps, or
changing the library's TypeScript, Swift, Kotlin, or Nitro specs.
license: MIT
metadata:
package: react-native-better-maps
version: "1.1.0"
commit: b9a178334913043b3aa2542fb528731debaad4f5
verified: "2026-08-21"
repository: https://github.com/gmi-software/react-native-better-maps
audience: library users and library contributors
tags: react-native, maps, mapkit, google-maps, nitro, jsi, markers, clustering, expo, ios, android
---
# react-native-better-maps
Native map view for React Native's New Architecture. One Nitro HybridView (`MapView`) backed by
Apple MapKit or Google Maps. Overlays are serialisable descriptors (not child views). Clustering
is implemented in Swift/Kotlin — not JavaScript, not shared C++, and not shared with
`react-native-better-clustering` (load that skill only when clustering on `react-native-maps`).
Paths like `package/src/...` are relative to a **library checkout**, not this skills repo.
## Version verification
```text
Package: react-native-better-maps
Version: 1.1.0
Commit: b9a178334913043b3aa2542fb528731debaad4f5
Verification date: 2026-08-21
```
```bash
npm view react-native-better-maps version
node -p "require('react-native-better-maps/package.json').version"
```
## When to use
- Installing / configuring the map (Google keys, Expo config plugin)
- Markers, polylines, polygons, circles, camera control
- Jank, flicker, markers disappearing at some zooms
- iOS vs Android or Apple vs Google behaviour differences
- Migrating from `react-native-maps`
- Changing TypeScript, Swift, Kotlin, Nitro specs, or the config plugin
## When NOT to use
| Situation | Instead |
| --- | --- |
| Using or debugging `react-native-maps` itself (not migrating) | Load the `react-native-maps` skill |
| Clustering on top of `react-native-maps` | Load the `react-native-better-clustering` skill |
| Mapbox / OSM tiles | Names exist in `MapProvider` but **throw at runtime** |
| Arbitrary React views as marker content | Unsupported on every provider |
| Web / Old Architecture / Expo Go | Native New Arch + development build only |
| Directions / geocoding / places | Outside this library |
## Core architecture
1. **One HybridView.** Everything is a prop or imperative method on `MapView`.
2. **Overlays are descriptors.** `<Marker>` renders `null`; props become `MarkerDescriptor`s.
Bulk `markers` bypasses child collection — preferred for large sets.
3. **Adapters own SDKs.** `MapProviderAdapter` owns MapKit or Google Maps.
4. **Provider changes remount.** Key is `` `${provider}:${googleMapId ?? ''}` `` — camera and
overlays must be re-supplied.
5. **Large sets take a background path.** Clustering on, or >500 descriptors → spatial index on
a background queue; smaller unclustered sets apply synchronously.
6. **No shared native package.** Native changes require **both** Swift and Kotlin (or an explicit
provider/platform carve-out).
## API guidance
```ts
import {
MapView, Marker, Polyline, Polygon, Circle,
regionFromCoordinate, distanceBetween,
} from 'react-native-better-maps';
```
That is the entire runtime surface (plus types). Full detail: [api.md](references/api.md).
## Problem → reference routing
| Problem | Start here |
| --- | --- |
| **Installation / blank map / Expo** | [setup.md](references/setup.md) |
| Google Maps blank/crash on iOS | setup → [ios.md](references/ios.md) |
| Markers, overlays, camera | [api.md](references/api.md) |
| Lag while panning/zooming | [performance.md](references/performance.md) |
| Marker re-render / flicker | [rendering.md](references/rendering.md) |
| Clustering / markers vanish when zoomed out | [clustering.md](references/clustering.md) |
| Provider / platform asymmetry | [ios.md](references/ios.md), [android.md](references/android.md) |
| Camera fights controlled `region` | [debugging.md](references/debugging.md) |
| **Migration from react-native-maps** | [migration.md](references/migration.md) |
| `animateCamera` hangs | debugging — **duration is seconds, not ms** |
| Architecture / contributing | [architecture.md](references/architecture.md), [contributing.md](references/contributing.md) |
## Canonical performance workflow
1. Baseline (release, real device, recorded number)
2. Define workload (count, provider, gesture)
3. Profile (Instruments / Android Studio Profiler)
4. Identify layer (JS / React / JSI conversion / native SDK)
5. Hypothesis → smallest change → re-measure → compare → regression note
Most "slow map" reports are layer 1: camera event → parent re-render → new `markers` array →
full descriptor re-cross. Region callbacks fire **once per gesture**, not per frame.
## Common mistakes
- Passing `duration: 300` to `animateCamera` (five-minute animation — unit is **seconds**)
- Expecting custom React marker views
- Using `openstreetmap` / `mapbox` provider values (they throw)
- Assuming Google-iOS honours `image` / `anchor` / `opacity` (it forces stock pins)
- Blaming clustering first when the parent rebuilds descriptors every camera event
- Measuring FPS on emulator / debug builds
## Troubleshooting
1. Blank/grey map → keys + Expo plugin + New Arch ([setup.md](references/setup.md))
2. Slow → name the layer ([performance.md](references/performance.md))
3. Flicker → stabilize `markers` / descriptor identity ([rendering.md](references/rendering.md))
4. Crash / odd prop → [debugging.md](references/debugging.md)
## Known limitations (high signal)
| Limitation | Consequence |
| --- | --- |
| `openstreetmap` / `mapbox` unimplemented | Throw during render |
| Google-iOS ignores marker visuals | Stock pins only; no warning |
| `animateCamera` duration in seconds | Default 0.25 s |
| Android `fitToCoordinates` / `region` apply collapse padding to max edge | Asymmetric fit padding does not port; `mapPadding` is per-edge |
| Unclustered LOD drops markers when zoomed out | By design, not a bug |
| No Expo Go | Development build required |
| No benchmark harness in repo | Measure yourself |
Full list and evidence rules: see references; do not invent thresholds.
Files in this package (12)
- SKILL.md 6 KB
- references/android.md 11 KB
- references/api.md 14 KB
- references/architecture.md 12 KB
- references/clustering.md 11 KB
- references/contributing.md 15 KB
- references/debugging.md 12 KB
- references/ios.md 10 KB
- references/migration.md 12 KB
- references/performance.md 17 KB
- references/rendering.md 9 KB
- references/setup.md 10 KB
Versions
The database has no other skills named react-native-better-maps.
Database snapshot: 13.11.2026 · package version 740c97ed16e1 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100react-native-maps
Expert guide to react-native-maps — MapView for iOS and Android backed by MapKit and Google Maps through React Native native components (not Nitro). Use when working with MapView, Marker, Callout, Polygon, Polyline, Circle, Overlay, Heatmap, Geojson, camera, or region from the… - 100react-native-better-clustering
Expert guide to react-native-better-clustering — a drop-in clustered MapView for react-native-maps backed by a C++ supercluster engine over Nitro/JSI. Use when installing, configuring, or debugging it; when clustering is slow, wrong, or flickering; when handling thousands of map… - 100create-react-native-library
Scaffolds React Native libraries with create-react-native-library for standalone libraries or local native modules and views. Use when creating or working on React Native libraries or adding native functionality in an existing app. - 100react-native-testing
Test React Native components with Jest and React Native Testing Library. Use when writing Jest or React Native Testing Library tests for React Native components. - 100react-native
React Native renderer for json-render that turns JSON specs into native mobile UIs. Use when working with @json-render/react-native, building React Native UIs from JSON, creating mobile component catalogs, or rendering AI-generated specs on mobile. - 95react-native-native-modules
Use when building or integrating native modules in React Native. Covers creating native modules, Turbo Modules, bridging native code, and accessing platform-specific APIs.