react-native-nitro-geolocation 1.1.2 → 1.1.4

package/README.md

@@ -0,0 +1,250 @@
+# react-native-nitro-geolocation
+
+[![NPM](https://img.shields.io/npm/v/react-native-nitro-geolocation)](https://www.npmjs.com/package/react-native-nitro-geolocation)
+
+**Simple and Modern Geolocation for React Native** — Powered by Nitro Modules with JSI
+
+A complete reimplementation of [`@react-native-community/geolocation`](https://github.com/michalchudziak/react-native-geolocation) for the React Native New Architecture, featuring:
+
+- 🎯 **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
+- 🧹 **Automatic cleanup** — No manual subscription management
+- 📱 **Consistent behavior** across iOS and Android
+- 🛠️ **DevTools Plugin** — Mock locations with interactive map (Rozenite)
+
+![react-native-nitro-geolocation](https://raw.githubusercontent.com/jingjing2222/react-native-nitro-geolocation/main/demo.gif)
+
+---
+
+## 📘 Documentation
+
+Full documentation available at:
+👉 [https://react-native-nitro-geolocation.pages.dev](https://react-native-nitro-geolocation.pages.dev)
+
+---
+
+## 🧭 Introduction
+
+React Native Nitro Geolocation provides **two APIs** to fit your needs:
+
+### 1. Modern API (Recommended)
+
+**Simple functional API** with direct calls and a single hook for tracking:
+
+```tsx
+import {
+  setConfiguration,
+  requestPermission,
+  getCurrentPosition,
+  useWatchPosition,
+} from "react-native-nitro-geolocation";
+
+// Configure once at app startup
+setConfiguration({
+  authorizationLevel: "whenInUse",
+  locationProvider: "auto",
+});
+
+// Request permission
+const status = await requestPermission();
+
+// Get current location
+const position = await getCurrentPosition({
+  enableHighAccuracy: true,
+});
+
+// Continuous tracking with hook
+function LocationTracker() {
+  const { position, error, isWatching } = useWatchPosition({
+    enabled: true,
+    enableHighAccuracy: true,
+    distanceFilter: 10,
+  });
+
+  if (error) return <Text>Error: {error.message}</Text>;
+  if (!position) return <Text>Waiting...</Text>;
+
+  return (
+    <Text>
+      {position.coords.latitude}, {position.coords.longitude}
+    </Text>
+  );
+}
+```
+
+**Benefits**:
+
+### 2. Legacy API (Compatibility)
+
+**Drop-in replacement** for `@react-native-community/geolocation`:
+
+```tsx
+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);
+```
+
+---
+
+## ⚡ Quick Start
+
+### 1. Installation
+
+```bash
+# 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:
+
+```bash
+cd ios && pod install
+```
+
+---
+
+### 2. iOS Setup
+
+Add permissions to your **Info.plist**:
+
+```xml
+<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>
+```
+
+---
+
+### 3. Android Setup
+
+Add permissions to **AndroidManifest.xml**:
+
+```xml
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+```
+
+Optional (for background):
+
+```xml
+<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+```
+
+---
+
+### 4. Development Tools (Optional)
+
+#### DevTools Plugin (Rozenite)
+
+> **Prerequisites**: Requires [Rozenite DevTools](https://github.com/rozenite/rozenite) to be installed.
+>
+> **API Compatibility**: Only works with the Modern API. Does not support the Legacy API (`/compat`).
+
+Mock geolocation data during development with an interactive map interface:
+
+![DevTools Plugin](https://raw.githubusercontent.com/jingjing2222/react-native-nitro-geolocation/main/devtools.gif)
+
+```bash
+npm install @react-native-nitro-geolocation/rozenite-plugin
+# or
+yarn add @react-native-nitro-geolocation/rozenite-plugin
+```
+
+**Setup**:
+
+```tsx
+import {
+  useGeolocationDevTools,
+  createPosition,
+} from "@react-native-nitro-geolocation/rozenite-plugin";
+
+function App() {
+  // Enable location mocking in development
+  useGeolocationDevTools({
+    initialPosition: createPosition("Seoul, South Korea"),
+  });
+
+  return <YourApp />;
+}
+```
+
+**Features**:
+
+- 🗺️ Interactive Leaflet map interface
+- 📍 Click to set location instantly
+- ⌨️ Arrow key navigation for precise control
+- 🏙️ 20 pre-configured city presets
+- ✏️ Manual latitude/longitude input
+- 📊 Real-time heading, speed, and accuracy calculation
+- 🌓 Dark mode support
+
+[See full DevTools guide →](https://react-native-nitro-geolocation.pages.dev/guide/devtools)
+
+---
+
+### 5. Usage
+
+#### Modern API (Recommended)
+
+```tsx
+// Get current location
+const position = await getCurrentPosition({ enableHighAccuracy: true });
+
+// Real-time tracking with hook
+const { position, error } = useWatchPosition({
+  enabled: true,
+  distanceFilter: 10
+});
+```
+
+#### Legacy API (Compatibility)
+
+```tsx
+import Geolocation from "react-native-nitro-geolocation/compat";
+
+Geolocation.getCurrentPosition((pos) => console.log(pos));
+const watchId = Geolocation.watchPosition((pos) => console.log(pos));
+Geolocation.clearWatch(watchId);
+```
+
+---
+
+---
+
+## 🔄 Migration from `@react-native-community/geolocation`
+
+Change the import to use `/compat` — 100% API compatible:
+```diff
+- import Geolocation from '@react-native-community/geolocation';
++ import Geolocation from 'react-native-nitro-geolocation/compat';
+```
+
+---
+
+## 📖 Learn More
+
+- [Introduction](https://react-native-nitro-geolocation.pages.dev/guide/)
+- [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)
+- [Legacy API Reference](https://react-native-nitro-geolocation.pages.dev/guide/legacy-api)
+- [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)
+
+---
+
+## License
+
+MIT License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-geolocation",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "⚡🚀Blazing-fast geolocation for React Native powered by Nitro Modules",
   "main": "src/index",
   "source": "src/index",

package/src/devtools/index.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { isDevtoolsEnabled } from "./index";
+
+const globalState = globalThis as typeof globalThis & {
+  __DEV__?: boolean;
+  __geolocationDevToolsEnabled?: boolean;
+};
+
+const originalState = {
+  hasDev: Object.prototype.hasOwnProperty.call(globalState, "__DEV__"),
+  dev: globalState.__DEV__,
+  hasDevtoolsEnabled: Object.prototype.hasOwnProperty.call(
+    globalState,
+    "__geolocationDevToolsEnabled"
+  ),
+  devtoolsEnabled: globalState.__geolocationDevToolsEnabled
+};
+
+describe("isDevtoolsEnabled", () => {
+  afterEach(() => {
+    if (originalState.hasDev) {
+      globalState.__DEV__ = originalState.dev;
+    } else {
+      globalState.__DEV__ = undefined;
+    }
+
+    if (originalState.hasDevtoolsEnabled) {
+      globalState.__geolocationDevToolsEnabled = originalState.devtoolsEnabled;
+    } else {
+      globalState.__geolocationDevToolsEnabled = undefined;
+    }
+  });
+
+  it("enables devtools only when React Native __DEV__ and the devtools flag are true", () => {
+    globalState.__DEV__ = true;
+    globalState.__geolocationDevToolsEnabled = true;
+
+    expect(isDevtoolsEnabled()).toBe(true);
+  });
+
+  it("ignores the devtools flag outside React Native __DEV__", () => {
+    globalState.__DEV__ = false;
+    globalState.__geolocationDevToolsEnabled = true;
+
+    expect(isDevtoolsEnabled()).toBe(false);
+  });
+
+  it("stays disabled when __DEV__ is unavailable", () => {
+    globalState.__DEV__ = undefined;
+    globalState.__geolocationDevToolsEnabled = true;
+
+    expect(isDevtoolsEnabled()).toBe(false);
+  });
+});

package/src/devtools/index.ts

@@ -1,5 +1,7 @@
 import type { GeolocationResponse } from "../types";
 
+declare const __DEV__: boolean;
+
 declare global {
   var __geolocationDevToolsEnabled: boolean | undefined;
   var __geolocationDevtools: DevtoolsState | undefined;
@@ -18,6 +20,10 @@ export function getDevtoolsState(): DevtoolsState {
   return globalThis.__geolocationDevtools;
 }
 
+function isReactNativeDev(): boolean {
+  return typeof __DEV__ !== "undefined" && __DEV__ === true;
+}
+
 export function isDevtoolsEnabled(): boolean {
-  return globalThis.__geolocationDevToolsEnabled === true;
+  return isReactNativeDev() && globalThis.__geolocationDevToolsEnabled === true;
 }