@nextbillion-ai/react-native-maps

v1.0.0

Published

5 months ago

React Native library for creating maps with NextBillion.ai Maps SDK for Android & iOS

0High
0Medium
0Low

qiuzhengshen

maps ios android nextbillion nb.ai react-native nextbillion-ai

NextBillion.ai React Native Maps

React Native library for creating maps with the NextBillion.ai Maps SDK for Android & iOS.

Documentation

https://docs.nextbillion.ai/docs/react-native-maps

Project Structure

This is a Yarn Workspaces monorepo containing a React Native library (@nextbillion-ai/react-native-maps) and its example applications.

Top-Level Overview

nextbillion-react-native/
├── src/                  # Library source code (TypeScript) — the core of the project
├── android/              # Android native module (Java)
├── ios/                  # iOS native module (Objective-C)
├── examples/             # Example apps (Yarn Workspaces)
│   ├── shared/           # Shared example code used by all example apps
│   ├── react-native-app/ # Pure React Native example app
│   └── expo-app/         # Expo example app
├── docs/                 # Documentation website
├── scripts/              # Code generation and build scripts
├── package.json          # Root: library metadata, workspaces config, Yarn 4
├── tsconfig.json         # TypeScript configuration
└── yarn.lock             # Dependency lock file

`src/` — Library Source Code (TypeScript)

This is the most important directory. All React components, hooks, and utility modules that users import from @nextbillion-ai/react-native-maps live here.

src/
├── index.ts              # Entry point — re-exports from NextbillionRN.ts
├── NextbillionRN.ts         # Aggregated exports: all components, modules, types
├── NBRNModule.ts         # Bridge to native module (NativeModules.NBRNModule)
│
├── components/           # React components — the public API users interact with
│   ├── MapView.tsx       # ★ Core: the map container component
│   ├── Camera.tsx        # ★ Core: controls map viewport (center, zoom, bounds)
│   ├── ShapeSource.tsx   # GeoJSON data source
│   ├── VectorSource.tsx  # Vector tile source
│   ├── RasterSource.tsx  # Raster tile source
│   ├── ImageSource.tsx   # Image overlay source
│   ├── Images.tsx        # Registers images for use in SymbolLayer
│   ├── FillLayer.tsx     # Renders polygon fills
│   ├── LineLayer.tsx     # Renders line features
│   ├── CircleLayer.tsx   # Renders point features as circles
│   ├── SymbolLayer.tsx   # Renders text labels and icons
│   ├── RasterLayer.tsx   # Renders raster tiles
│   ├── HeatmapLayer.tsx  # Renders heatmap visualization
│   ├── FillExtrusionLayer.tsx  # 3D extruded polygons
│   ├── BackgroundLayer.tsx     # Map background color/pattern
│   ├── Light.tsx         # Controls 3D lighting
│   ├── PointAnnotation.tsx     # Tap-able map markers
│   ├── MarkerView.tsx    # Custom React Native views as markers
│   ├── Annotation.tsx    # Legacy annotation component
│   ├── Callout.tsx       # Popup displayed on marker tap
│   ├── UserLocation.tsx  # Shows user's GPS position on map
│   └── UserLocationPuck.tsx    # Blue dot style user location indicator
│
├── hooks/                # React hooks for native bridge communication
│   ├── useNativeBridge.ts  # ★ Key: sends commands to native modules (Android/iOS)
│   ├── useNativeRef.ts     # Manages refs to native components
│   ├── useAbstractLayer.ts # Shared logic for all Layer components
│   ├── useAbstractSource.ts# Shared logic for all Source components
│   └── useOnce.ts          # Run effect only once
│
├── modules/              # Non-UI feature modules
│   ├── location/
│   │   └── LocationManager.ts   # GPS location tracking
│   ├── offline/
│   │   ├── OfflineManager.ts    # Download/manage offline map packs
│   │   ├── OfflinePack.ts       # Single offline pack object
│   │   └── OfflineCreatePackOptions.ts
│   └── snapshot/
│       ├── SnapshotManager.ts   # Capture static map images
│       └── SnapshotOptions.ts
│
├── utils/                # Utility functions
│   ├── index.ts          # Platform detection, native command runner
│   ├── Logger.ts         # Log level control for native SDK
│   ├── BridgeValue.ts    # Serializes style values for native bridge
│   ├── StyleValue.ts     # Style property value processing
│   ├── filterUtils.ts    # Layer filter expression helpers
│   ├── makeNativeBounds.ts # Converts bounds for native API
│   └── animated/         # Animation utilities
│       ├── Animated.ts
│       ├── AnimatedPoint.ts
│       ├── AnimatedShape.ts
│       └── AnimatedRouteCoordinatesArray.ts
│
├── types/                # TypeScript type definitions
│   ├── NextbillionRNStyles.ts  # ★ All style property types (generated)
│   ├── NextbillionRNEvent.ts   # Event type definitions
│   ├── OnPressEvent.ts      # Map/feature press event
│   ├── BaseProps.ts         # Shared component prop types
│   └── CameraMode.ts       # Camera animation mode enum
│
└── plugin/               # Expo config plugin (auto-configures native projects)
    ├── withMapLibre.ts
    ├── android.ts
    ├── ios.ts
    └── MapLibrePluginProps.ts

Key concepts for beginners:

Components = UI building blocks. You compose a map by nesting components: <MapView> → <Camera> + <ShapeSource> → <FillLayer>. This follows the "source + layer" model from the map style specification.
Hooks = native bridge. React hooks in hooks/ handle communication between JavaScript and native code (Java/ObjC). You rarely need to touch these.
Modules = non-UI features. Offline maps, location tracking, and screenshot capture are handled through singleton managers.

`android/` — Android Native Module (Java)

android/src/main/java/ai/nextbillion/reactnative/
├── NBRNPackage.java              # Registers all native modules and view managers
├── modules/
│   ├── NBRNModule.java           # ★ Main native module (style URLs, access tokens)
│   ├── NBRNOfflineModule.java    # Offline pack management
│   └── NBRNSnapshotModule.java   # Map snapshot capture
├── components/
│   ├── mapview/
│   │   ├── NBRNMapView.java      # ★ Core map view implementation
│   │   └── NBRNMapViewManager.java  # React Native ViewManager bridge
│   ├── camera/                   # Camera control
│   ├── styles/
│   │   ├── layers/               # All layer types (Fill, Line, Circle, Symbol...)
│   │   └── sources/              # All source types (Shape, Vector, Raster, Image)
│   ├── annotation/               # Point annotations, callouts, markers
│   ├── images/                   # Image management
│   └── location/                 # Native user location indicator
├── events/                       # Native event definitions
├── location/                     # Location tracking
├── utils/                        # GeoJSON parsing, image downloading, etc.
└── http/
    └── CustomHeadersInterceptor.java  # Inject custom HTTP headers

Each React component in src/components/ has a corresponding *Manager.java (ViewManager) and implementation class on Android.

`ios/` — iOS Native Module (Objective-C)

ios/NBRN/
├── NBRN.h                  # Umbrella header
├── NBRNModule.h/.m         # ★ Main native module
├── NBRNMapView.h/.m        # ★ Core map view
├── NBRNMapViewManager.h/.m # React Native ViewManager bridge
├── NBRNCamera.h/.m         # Camera control
├── NBRN*Layer.h/.m         # Layer implementations (Fill, Line, Circle, Symbol...)
├── NBRN*Source.h/.m        # Source implementations (Shape, Vector, Raster, Image)
├── NBRNPointAnnotation.h/.m # Map markers
├── NBRNOfflineModule.h/.m  # Offline map management
├── NBRNLocationManager.h/.m # GPS location
└── NBRNSnapshotModule.h/.m # Map screenshots

Mirrors the Android structure. Each *Manager file is the ViewManager bridge that React Native calls.

`examples/` — Example Applications

examples/
├── shared/                      # ★ Shared examples (the code you edit most)
│   └── src/
│       ├── App.tsx              # Root component (permissions, navigation)
│       ├── Examples.tsx         # Navigation menu listing all examples
│       └── examples/
│           ├── Map/
│           │   ├── ShowMap.tsx          # ★ Basic map display
│           │   ├── TwoMapViews.tsx     # Multiple maps
│           │   ├── LocalStyleJSON.tsx  # Load style from local JSON
│           │   └── CreateOfflineRegion.tsx
│           ├── Camera/              # Camera movement examples
│           ├── Annotations/         # Markers and callouts
│           ├── FillRasterLayer/     # Layer styling examples
│           ├── SymbolCircleLayer/   # Icons and circle markers
│           ├── UserLocation/        # GPS tracking examples
│           ├── Animations/          # Animated map features
│           └── Sources/             # PMTiles and custom sources
│
├── react-native-app/            # Pure React Native host app
│   ├── package.json             # Dependencies: react-native 0.76.9
│   ├── android/                 # Android project (Gradle, manifests)
│   └── ios/                     # iOS project (Xcode, Podfile)
│
└── expo-app/                    # Expo host app
    └── package.json

How examples work: react-native-app and expo-app are thin shells that import examples/shared. When you want to add or modify examples, edit files in examples/shared/src/examples/.

Architecture Diagram

┌─────────────────────────────────────────────────┐
│                 Your App Code                    │
│  import { MapView, Camera } from                │
│         '@nextbillion-ai/react-native-maps'        │
└──────────────────────┬──────────────────────────┘
                       │
          ┌────────────▼────────────┐
          │    src/ (TypeScript)     │
          │  Components + Hooks     │
          │  ┌──────────────────┐   │
          │  │  useNativeBridge │   │  ← JS ↔ Native communication
          │  └────────┬─────────┘   │
          └───────────┼─────────────┘
                      │
         ┌────────────┼────────────┐
         │ React Native Bridge     │
         ├────────────┼────────────┤
         │            │            │
    ┌────▼────┐  ┌────▼────┐
    │ android/ │  │  ios/    │
    │  (Java)  │  │ (ObjC)  │
    └────┬─────┘  └────┬────┘
         │             │
    ┌────▼─────────────▼────┐
    │ NextBillion.ai Maps SDK │
    │  (C++ rendering core)   │
    └─────────────────────────┘

Quick Reference: Where to Find Things

| I want to... | Look at | |---------------------------------------|--------------------------------------------| | Modify the example map | examples/shared/src/examples/Map/ShowMap.tsx | | Add a new example | examples/shared/src/examples/ + register in Examples.tsx | | Understand a component's props | src/components/<Component>.tsx | | See all exported APIs | src/NextbillionRN.ts | | Change Android native behavior | android/src/main/java/ai/nextbillion/reactnative/ | | Change iOS native behavior | ios/NBRN/ | | Manage offline maps | src/modules/offline/OfflineManager.ts | | Track user GPS location | src/modules/location/LocationManager.ts | | Modify style types (auto-generated) | scripts/codegen.ts → src/types/NextbillionRNStyles.ts | | Configure Expo plugin | src/plugin/withMapLibre.ts | | Run Android example app | cd examples/react-native-app && yarn android | | Run iOS example app | cd examples/react-native-app && yarn ios |

Running on Android Device

Prerequisites

| Item | Details | |------|---------| | Node.js | Install via nvm or Homebrew | | Yarn 4 | Enabled via Corepack (corepack enable) | | Android SDK | Installed via Android Studio | | JDK 21 | Bundled with Android Studio (Gradle 8.10.2 is incompatible with Java 24+) |

One-time Setup

# 1. Enable Corepack (for Yarn 4 support)
corepack enable

# 2. Install dependencies from the monorepo root
cd /path/to/nextbillion-react-native
yarn install

# 3. Configure Android SDK path
echo "sdk.dir=$HOME/Library/Android/sdk" > examples/react-native-app/android/local.properties

Run on Device

Step 1: Set JAVA_HOME (required in every terminal window)

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

Step 2: Connect Device & Port Forwarding

# Verify device is connected (USB debugging must be enabled)
adb devices

# Forward Metro port to device
adb reverse tcp:8081 tcp:8081

# If multiple devices are connected, specify the serial number
# adb -s <SERIAL> reverse tcp:8081 tcp:8081

Step 3: Start Metro Dev Server (Terminal 1)

cd examples/react-native-app
yarn start

Step 4: Build & Install (Terminal 2)

cd examples/react-native-app
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
yarn android

First build takes ~12 minutes. Subsequent incremental builds are much faster.

Troubleshooting

| Issue | Solution | |-------|----------| | EADDRINUSE: address already in use :::8081 | lsof -ti:8081 \| xargs kill -9 | | Failed to connect to localhost:8081 | adb reverse tcp:8081 tcp:8081 | | Unsupported class file major version 68 | Set JAVA_HOME to Android Studio's JDK 21 | | Multiple device conflict | adb -s <SERIAL> reverse tcp:8081 tcp:8081 | | White screen on device | Shake device → Reload, or adb shell input keyevent 82 |

Contributing & Development

Read the CONTRIBUTING guide to get familiar with how we do things around here and set up your local development environment.

Support

For questions or issues, please visit NextBillion.ai or open an issue on GitHub.