react-native-nitro-geolocation

Nitro-powered geolocation for modern React Native apps

A native iOS/Android geolocation module for React Native 0.75+ apps using the New Architecture and Nitro Modules. Start by replacing @react-native-community/geolocation with /compat, then move to a typed Modern API when you are ready. The current release line adds web support for Modern and /compat foreground geolocation plus a native Background Location API for tracking, geofencing, storage recovery, Headless JS, and HTTP sync.

• 🎯 Simple functional API — Direct function calls, no complex abstractions
• ⚡ JSI-powered performance — Direct native calls without Bridge overhead
• 🔁 Compat API — Drop-in compatible with the core native community API
• 🧹 Automatic cleanup — No manual subscription management
• 📱 Consistent behavior across iOS and Android
• 🛠️ DevTools Plugin — Mock locations with interactive map (Rozenite)

📘 Documentation

Full documentation available at: 👉 https://react-native-nitro-geolocation.pages.dev

When should I use this?

| Use case | Recommendation | |---|---| | Bare React Native 0.75+ app with New Architecture/Nitro enabled | Use Nitro Geolocation | | Migrating from @react-native-community/geolocation | Start with /compat | | New Architecture / Nitro-based app | Recommended | | Expo development build or custom native build | Supported with native setup | | Expo managed app without native rebuild | Use expo-location | | Web support required | Use the Modern API root import or /compat callback API | | Full background tracking / geofencing | Use react-native-nitro-geolocation/background |

Web support is available for the Modern API root import and the /compat subpath. Browser builds resolve both entries to implementations backed by navigator.geolocation and do not load Nitro native bindings. Background location remains native-only.

🧭 Introduction

React Native Nitro Geolocation provides three public API surfaces to fit your needs:

1. Modern API (Recommended)

Simple functional API with direct calls and a single hook for tracking:

import {
  setConfiguration,
  requestPermission,
  getCurrentPosition,
} from "react-native-nitro-geolocation";

setConfiguration({
  authorizationLevel: "whenInUse",
  locationProvider: "auto",
});

const status = await requestPermission();

if (status === "granted") {
  const position = await getCurrentPosition({
    accuracy: { android: "high", ios: "best" },
    timeout: 15_000,
  });
}

See the Modern API guide for watches, geocoding, heading, cached reads, Android settings, and iOS accuracy authorization.

2. Compat API (Compatibility)

Drop-in compatible with the core native @react-native-community/geolocation API:

import Geolocation from "react-native-nitro-geolocation/compat";

Geolocation.getCurrentPosition(
  (position) => console.log(position),
  (error) => console.error(error),
  { enableHighAccuracy: true }
);

const watchId = Geolocation.watchPosition((position) => console.log(position));
Geolocation.clearWatch(watchId);

The /compat subpath covers the core native community API, including setRNConfiguration, requestAuthorization, getCurrentPosition, watchPosition, clearWatch, and stopObserving. It also has a browser entry for callback-style foreground geolocation. See the Compat API guide for the full compatibility matrix and option notes.

3. Background API

Native background tracking, geofencing, activity events, Android Headless JS, HTTP sync, and stored event recovery should use the explicit background subpath.

Background location is native-only. Browser builds expose unsupported stubs so web bundles can still import shared code safely. Start with the Background Location guide for permissions, start/stop, geofencing, storage recovery, and native sync.

⚡ Quick Start

1. Installation

# Install Nitro core and Geolocation module
yarn add react-native-nitro-modules react-native-nitro-geolocation

# or using npm
npm install react-native-nitro-modules react-native-nitro-geolocation

Rebuild your native app:

cd ios && pod install

2. iOS Setup

Add permissions to your Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app requires access to your location while it's in use.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app requires access to your location at all times.</string>

For background tracking, also enable the location background mode in UIBackgroundModes.

3. Android Setup

Add permissions to AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Optional (for background):

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Full background tracking uses a foreground service on Android. Add the full permission set from the Android background setup guide when using react-native-nitro-geolocation/background, including Android 13+ POST_NOTIFICATIONS for the tracking notification.

4. Continue In The Docs

Use the docs site for the detailed flows:

• Quick Start - install, set native permissions, and read your first location.
• Modern API - accuracy presets, watches, Android settings, cached reads, geocoding, heading, and iOS accuracy authorization.
• Compat API - callback compatibility and web behavior.
• Background Location - native background tracking, geofencing, storage recovery, Headless JS, and HTTP sync.
• Migration Assistance - choose the community or service migration path.
• Expo Development Builds - use the package in Expo custom native builds.
• DevTools Plugin - mock locations during development.

📖 Learn More

• Introduction
• Quick Start Guide
• Modern API Reference
• Compat API Reference
• Migration Skills
• Community Migration
• Service Migration
• Expo Development Build Guide
• DevTools Plugin Guide
• Why Nitro Module?
• Benchmark Results

License

MIT License.