How maplibre/maplibre-react-native works
Project Type and Purpose
• This is a cross-platform React Native library (“MapLibre React Native”) that exposes native MapLibre SDK functionality on Android and iOS to JavaScript.
• The goal is to provide React Native components (e.g., MapView, Layer, Source) and modules (offline packs, snapshots, location) by bridging JS to native MapLibre.
Key Architectural Components
a. JavaScript Layer (React Native)
• src/components: React components (MapView, annotation layers, etc.)
• src/modules: JS module wrappers (location, offline, snapshot)
• src/hooks, src/utils: support code (hooks into the native bridge, style value parsers, logging)
• examples & docs: usage examples and Docusaurus documentation site
b. React Native Bridge
• src/MapLibreRN.ts & src/MLRNModule.ts: JS/Nativemodule registration
• Gradle plugin (scripts/codegen.ts) and podspec: generate native-style bindings
c. Native Android Implementation
• android/src/main/java/org/maplibre/reactnative: Java package exposing ReactPackage (MLRNPackage), ViewManagers, NativeModules
• Relies on MapLibre Native Android SDK (C++ core + Java bindings)
• Location engine providers under android/src/main/location-engine-*
d. Native iOS Implementation
• ios/MLRN: Objective-C classes (MLRNMapViewManager, MLRNModule, layer/source managers, modules)
• Podspec (maplibre-react-native.podspec) integrates MapLibre Native iOS SDK
e. External Services & Resources
• Tile servers (online vector/raster sources)
• Offline pack file storage
• Device location services (via Google location or default engine)
Interactions and Data Flows
• JS React components call native APIs via the React Native bridge →
native ViewManagers / NativeModules on Android/iOS.
• Native code interacts with the underlying MapLibre SDK to load maps, manage layers, query features, or start offline packs.
• Events (click, camera change, location updates) are emitted back through the bridge into JS event handlers.
• Native HTTP interceptors inject custom headers (CustomHeadersInterceptor.java / MLRNCustomHeaders.h).
• Offline caching reads/writes pack data to local storage (SQLite or filesystem) and triggers JS callbacks.
• Location modules access device sensors and feed location events back to JS.
Architectural Patterns & Principles
• Bridge Pattern: clear separation between JS API surface and native implementations.
• Facade: JS components offer a simplified facade over complex native SDKs.
• Modular design: separate modules for offline, snapshot, logging, location, enabling independent testing.
• Code Generation: EJS templates under scripts/ for generating style binding classes, reducing boilerplate.