react-native-nitro-geolocation 1.2.0 → 1.2.2

package/README.md

@@ -2,13 +2,16 @@
 
 [![NPM](https://img.shields.io/npm/v/react-native-nitro-geolocation)](https://www.npmjs.com/package/react-native-nitro-geolocation)
 
-**Simple Native Geolocation for React Native** — Powered by Nitro Modules with JSI
+**Nitro-powered geolocation for modern React Native apps**
 
-A complete reimplementation of [`@react-native-community/geolocation`](https://github.com/michalchudziak/react-native-geolocation) for the React Native New Architecture, featuring:
+A native iOS/Android geolocation module for React Native 0.75+ and New
+Architecture apps. Start by replacing
+[`@react-native-community/geolocation`](https://github.com/michalchudziak/react-native-geolocation)
+with `/compat`, then move to a typed Modern API when you are ready.
 
 - 🎯 **Simple functional API** — Direct function calls, no complex abstractions
-- ⚡ **JSI-powered performance** — Direct native calls without the Bridge
-- 🔁 **100% API compatibility** via `/compat` for easy migration
+- ⚡ **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)
@@ -24,6 +27,24 @@ Full documentation available at:
 
 ---
 
+## When should I use this?
+
+| Use case | Recommendation |
+|---|---|
+| Bare React Native 0.75+ app | 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 `@react-native-community/geolocation` or `expo-location` for now |
+| Full background tracking / geofencing | Use a dedicated background-location library |
+
+Web is not supported in `v1.2.x`. The community package handles web by
+delegating to the browser `navigator.geolocation` API; this package currently
+targets native Nitro bindings. A `/compat` web fallback is planned for `v1.3`.
+
+---
+
 ## 🧭 Introduction
 
 React Native Nitro Geolocation provides **two APIs** to fit your needs:
@@ -121,7 +142,8 @@ function LocationTracker() {
 
 ### 2. Compat API (Compatibility)
 
-**Drop-in replacement** for `@react-native-community/geolocation`:
+Drop-in compatible with the core native
+`@react-native-community/geolocation` API:
 
 ```tsx
 import Geolocation from "react-native-nitro-geolocation/compat";
@@ -136,6 +158,19 @@ const watchId = Geolocation.watchPosition((position) => console.log(position));
 Geolocation.clearWatch(watchId);
 ```
 
+#### Compat API coverage
+
+| Community API | Nitro `/compat` | Notes |
+|---|---:|---|
+| `setRNConfiguration` | Supported | Android `auto` currently maps to the platform provider; set `playServices` explicitly for fused location. |
+| `requestAuthorization` | Supported | iOS authorization follows configured `Info.plist` keys and `authorizationLevel`. |
+| `getCurrentPosition` | Supported | Keeps the legacy callback and error shape. |
+| `watchPosition` | Supported | Returns a numeric watch id. |
+| `clearWatch` | Supported | Clears a watch id from `watchPosition`. |
+| `stopObserving` | Supported | Preserved for legacy cleanup compatibility. |
+| `navigator.geolocation` polyfill | Not supported in `v1.2.x` | Planned for `v1.3`. |
+| Web | Not supported in `v1.2.x` | Planned as a `/compat` browser fallback in `v1.3`. |
+
 ---
 
 ## ⚡ Quick Start
@@ -188,7 +223,34 @@ Optional (for background):
 
 ---
 
-### 4. Development Tools (Optional)
+### 4. Android Reliability
+
+- Uses Google Play Services fused location when `locationProvider:
+  "playServices"` is set.
+- Keeps `locationProvider: "auto"` on Android's platform `LocationManager` by
+  default. Set `playServices` explicitly when you want fused location behavior.
+- Supports native settings resolution through `requestLocationSettings`.
+- Supports approximate/coarse location handling through permissions and
+  Android `granularity`.
+- Supports explicit cached reads through `getLastKnownPosition`.
+- Provides structured Modern API errors such as `PLAY_SERVICE_NOT_AVAILABLE`,
+  `SETTINGS_NOT_SATISFIED`, and `TIMEOUT`.
+
+---
+
+### 5. Expo Development Builds
+
+This package requires native Nitro bindings, so it is not an Expo Go module.
+Use Expo prebuild, a development build, or another custom native build flow,
+then apply the same iOS and Android native permission setup shown above.
+
+Managed Expo apps that cannot rebuild native code should use `expo-location`.
+See the [Expo development build guide](https://react-native-nitro-geolocation.pages.dev/guide/expo-development-build)
+for the supported setup path.
+
+---
+
+### 6. Development Tools (Optional)
 
 #### DevTools Plugin (Rozenite)
 
@@ -238,7 +300,7 @@ function App() {
 
 ---
 
-### 5. Usage
+### 7. Usage
 
 #### Modern API (Recommended)
 
@@ -291,12 +353,67 @@ Geolocation.clearWatch(watchId);
 
 ## 🔄 Migration from `@react-native-community/geolocation`
 
-Change the import to use `/compat` — 100% API compatible:
+The safest migration is two-step: switch imports to `/compat` first, verify
+the app, then move call sites to the Modern API where it improves ownership,
+permission timing, cache behavior, or Android settings handling.
+
+For Modern API migration, install the Agent Skills-compatible migration
+playbook from this repository. It is migration assistance for coding agents, not
+a fully automatic migration. The skill first runs a package-manager-aware
+compat bootstrap script that installs the Nitro packages, rewrites legacy import
+sources to `/compat`, and removes `@react-native-community/geolocation`. After
+that safe mechanical step, it guides the agent to refactor compat call sites to
+Modern API best practices using explicit criteria for permission timing, React
+lifecycle ownership, watch cleanup, cache-vs-fresh location reads, accuracy, and
+Android provider/settings handling.
+
+With the Vercel Labs `skills` CLI:
+
+```bash
+npx skills add jingjing2222/react-native-nitro-geolocation --skill react-native-nitro-geolocation-modern-migration
+```
+
+The skill source is
+[`skills/react-native-nitro-geolocation-modern-migration/SKILL.md`](https://github.com/jingjing2222/react-native-nitro-geolocation/tree/main/skills/react-native-nitro-geolocation-modern-migration).
+The bundled bootstrap script is
+[`skills/react-native-nitro-geolocation-modern-migration/scripts/migrate-to-compat.mjs`](https://github.com/jingjing2222/react-native-nitro-geolocation/tree/main/skills/react-native-nitro-geolocation-modern-migration/scripts/migrate-to-compat.mjs).
+
+For a drop-in compatibility migration, change the import to use `/compat`:
+
 ```diff
 - import Geolocation from '@react-native-community/geolocation';
 + import Geolocation from 'react-native-nitro-geolocation/compat';
 ```
 
+Then migrate individual call sites to the Modern API:
+
+```diff
+- Geolocation.getCurrentPosition(onSuccess, onError, {
+-   enableHighAccuracy: true,
+-   timeout: 15000,
+- });
++ const position = await getCurrentPosition({
++   accuracy: { android: "high", ios: "best" },
++   timeout: 15000,
++ });
+```
+
+See the [migration demo](https://react-native-nitro-geolocation.pages.dev/guide/migration-demo)
+for the full community import → `/compat` → Modern API path.
+
+---
+
+## Benchmark scope
+
+The benchmark measures cached `getCurrentPosition` reads over 1000 iterations ×
+5 runs on an iPhone 14 Pro with React Native 0.81.4. It measures the
+JS-to-native path for cached locations, not cold GPS acquisition, permission
+dialogs, provider availability, or OS throttling.
+
+For cached location reads, Nitro removes Bridge overhead. This does not make GPS
+acquisition itself 22x faster; it makes cached reads and the JS-to-native call
+path cheaper.
+
 ---
 
 ## 📖 Learn More
@@ -305,6 +422,8 @@ Change the import to use `/compat` — 100% API compatible:
 - [Quick Start Guide](https://react-native-nitro-geolocation.pages.dev/guide/quick-start)
 - [Modern API Reference](https://react-native-nitro-geolocation.pages.dev/guide/modern-api)
 - [Compat API Reference](https://react-native-nitro-geolocation.pages.dev/guide/compat-api)
+- [Migration Demo](https://react-native-nitro-geolocation.pages.dev/guide/migration-demo)
+- [Expo Development Build Guide](https://react-native-nitro-geolocation.pages.dev/guide/expo-development-build)
 - [DevTools Plugin Guide](https://react-native-nitro-geolocation.pages.dev/guide/devtools)
 - [Why Nitro Module?](https://react-native-nitro-geolocation.pages.dev/guide/why-nitro-module)
 - [Benchmark Results](https://react-native-nitro-geolocation.pages.dev/guide/benchmark)

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/NitroGeolocation.kt

@@ -747,6 +747,8 @@ class NitroGeolocation(
     // MARK: - Helper Functions - Provider Selection
 
     private fun requiresPlayServices(): Boolean {
+        // TODO: Switch auto/default Android provider selection to prefer
+        // Google Play Services when available.
         return configuration?.locationProvider == LocationProvider.PLAYSERVICES
     }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-native-nitro-geolocation",
-  "version": "1.2.0",
-  "description": "⚡🚀Blazing-fast geolocation for React Native powered by Nitro Modules",
+  "version": "1.2.2",
+  "description": "Nitro-powered native geolocation for modern React Native apps",
   "main": "src/index",
   "source": "src/index",
   "exports": {
@@ -26,6 +26,22 @@
   },
   "author": "jingjing2222",
   "license": "MIT",
+  "keywords": [
+    "react-native",
+    "geolocation",
+    "location",
+    "gps",
+    "ios",
+    "android",
+    "nitro",
+    "nitro-modules",
+    "jsi",
+    "new-architecture",
+    "fused-location",
+    "geocoding",
+    "heading",
+    "expo-dev-client"
+  ],
   "homepage": "https://react-native-nitro-geolocation.pages.dev",
   "repository": {
     "type": "git",

package/src/NitroGeolocation.nitro.ts

@@ -67,7 +67,7 @@ export interface GeolocationConfiguration {
    * Android: Location provider
    * - 'playServices': Use Google Play Services (fused location)
    * - 'android_platform': Use Android platform LocationManager
-   * - 'auto': Auto-select (prefer Play Services if available)
+   * - 'auto': Use Android platform LocationManager by default
    */
   locationProvider?: LocationProvider;
 }

package/src/publicTypes.ts

@@ -79,6 +79,12 @@ export type GeolocationConfiguration = Omit<
    */
   autoRequestPermission?: boolean;
 
+  /**
+   * Android location provider.
+   *
+   * `auto` currently uses Android's platform `LocationManager` by default.
+   * Set `playServices` explicitly to use Google Play Services fused location.
+   */
   locationProvider?: LocationProvider;
 };
 
@@ -92,5 +98,11 @@ export type CompatGeolocationConfiguration = Omit<
   CompatGeolocationConfigurationInternal,
   "locationProvider"
 > & {
+  /**
+   * Android location provider.
+   *
+   * `auto` currently uses Android's platform `LocationManager` by default.
+   * Set `playServices` explicitly to use Google Play Services fused location.
+   */
   locationProvider?: LocationProvider;
 };