How twillouer/maps works
Project Type & Purpose
• This is a multi-platform, open-source React Native SDK that exposes Mapbox Maps functionality to React Native apps.
• It consists of:
• A JavaScript/TypeScript layer of React Native components & modules (“javascript” folder).
• Native bridges and modules for Android (“android/rctmgl” with Java/Kotlin) and iOS (“ios/RCTMGL-v10” with Obj-C & Swift, plus legacy “ios/RCTMGL”).
• Code-generation & build scripts under “scripts” and “plugin” to generate style APIs and to support Expo.
• An example React Native application demonstrating usage (“example”).
High-Level File-Structure Analysis
• Top-level directories:
• android/ – Android native module source, Gradle setup, JNI bindings for new v10 & legacy SDKs.
• ios/ – iOS native module in Obj-C/Swift, two versions (v10 and legacy).
• javascript/ – React Native component tree: components, modules (location, offline, snapshot), utils, web adapters.
• plugin/ – Expo config plugin to inject native dependencies.
• example/ – RN example app with platform folders, demonstrating integration.
• scripts/ – Codegen helpers, JSDoc→Markdown, style-spec downloader.
• docs/ – Markdown API docs.
• style-spec/ – Official Mapbox style spec JSON.
Core Components & Data Flow
a. JavaScript Layer
• React Native components (MapView, Layers, Sources, Cameras, Annotations).
• JS modules for location, offline packs, snapshot.
• Utilities: BridgeValue conversion, geometry parsing, style functions.
b. React Native Bridge
• Each JS component wraps a NativeBridgeComponent and calls NativeModules via the RN bridge (RCT_EXPORT_METHOD).
c. Native Modules
• Android: RCTMGLPackage registers modules & view managers → Mapbox SDK classes.
• iOS: RCTMGLModule, view managers, and RCTMGL<Feature> classes → Mapbox iOS SDK.
• Modules implement APIs: location, offline, snapshot, custom headers.
d. Underlying Map SDK
• Linked libs: Mapbox v10, Maplibre, and legacy mapbox-gl; chosen via RNMapboxMapsImpl.
• JS Components (React Native)
• RN Bridge Layer
• Android Native Module (Java/Kotlin)
• iOS Native Module (Obj-C/Swift)
• Mapbox SDKs (v10, maplibre, legacy)
• Code-gen Pipeline (scripts/style-spec)
• Example App (top-level consumer)
• Expo Plugin (optional integration)
• External Mapbox Services (tile APIs, telemetry)
Relationships & Interactions
JS Components → RN Bridge → { Android Module ↔ Mapbox-Android SDK; iOS Module ↔ Mapbox-iOS SDK }
Code-gen Scripts → generate Native & JS style‐factory code
Example App → imports JS Layer & loads via plugin or autolinking
Expo Plugin → modifies native projects to include modules
Native Modules → fetch map tiles & telemetry from external Mapbox APIs
Architectural Patterns & Principles
• Bridge Pattern: decoupling JS API from native implementation.
• Modularization: separate concerns (components, modules, utils).
• Code Generation: templated style APIs created from a single, authoritative style-spec.
• Multi-platform Abstraction: same JS API surface, different native impls.