jingjing2222/react-native-nitro-geolocation/community-migration

Community Geolocation Migration

Use a two-phase migration:

1. Bootstrap safely to /compat so the app stops depending on

@react-native-community/geolocation.

1. Refactor from /compat to the recommended API shape.

Do not start by hand-converting every callback call site. First make the mechanical package/import migration small and reversible, verify it, then do the semantic API refactor.

Workflow

1. Inspect the target app root and check the worktree state.
2. Resolve scripts/migrate-to-compat.mjs relative to this SKILL.md.
3. Run a dry run from the target app root:

``bash node <skill-dir>/scripts/migrate-to-compat.mjs --root <app-root> --dry-run ``

1. If the dry run is expected, run it for real:

``bash node <skill-dir>/scripts/migrate-to-compat.mjs --root <app-root> ` The script detects packageManager or lockfiles, installs missing react-native-nitro-modules and react-native-nitro-geolocation, rewrites @react-native-community/geolocation import sources to react-native-nitro-geolocation/compat, removes @react-native-community/geolocation, and prints package-manager-specific validation commands that exist in the app's package.json`.

1. Run the printed validation commands. Do not hardcode yarn, npm, pnpm,

or bun; use the detected package manager and only scripts that exist.

1. Refresh the public docs context when network is available:

``bash curl -fsSL https://react-native-nitro-geolocation.pages.dev/llms.txt curl -fsSL https://react-native-nitro-geolocation.pages.dev/llms-full.txt ` Read llms.txt first as the docs index. Use llms-full.txt only when you need exact API names, option semantics, or examples for the API, Compat API, quick start, or platform setup. If the app already pins an older react-native-nitro-geolocation version, confirm an API exists in node_modules/react-native-nitro-geolocation` or the installed package types before using docs-only APIs.

1. Find remaining community geolocation usage:

``bash rg "@react-native-community/geolocation|react-native-nitro-geolocation/compat|setRNConfiguration|requestAuthorization|watchPosition|clearWatch|stopObserving|navigator\\.geolocation" ` Treat navigator.geolocation` as a manual-review compatibility site, not as the primary migration scope.

1. Inspect each call site before refactoring. Identify whether it is in a React

function component, class component, hook, service module, background task, or test.

1. Replace compat imports with named imports from

react-native-nitro-geolocation. Remove Geolocation default-object usage when the migrated file no longer needs it.

1. Convert one-shot and permission APIs to async/await or explicit Promise

chains. Preserve existing loading, state, and error behavior.

1. Migrate watches to useWatchPosition only where React hook rules allow it.

Use watchPosition plus unwatch for non-component code, class components, callbacks, conditionals, and services.

1. Flag unsupported or semantic changes in comments or the final report instead

of guessing.

1. Run the target app's relevant detected validation commands again. If

validating an actual migrated app flow on device, use agent-device when available.

Docs Reference

Use these docs endpoints as the source of truth during the API refactor:

• https://react-native-nitro-geolocation.pages.dev/llms.txt - concise index

of available docs pages.

• https://react-native-nitro-geolocation.pages.dev/llms-full.txt - complete

rendered docs content for agent consumption.

Prefer llms.txt for navigation and llms-full.txt for exact API details. Do not paste or load the full docs into the final answer; use them to check facts before editing. If network is unavailable, fall back to local package docs, README files, and TypeScript declarations in the installed package.

Best Practice Target

The final migration is not just "no type errors." Prefer this target state:

• No app runtime imports from @react-native-community/geolocation,

navigator.geolocation, or react-native-nitro-geolocation/compat. Keep /compat only in deliberate compatibility examples, tests, or migration fallback code the user explicitly wants to preserve.

• Configure once near app startup with setConfiguration(). Do not leave

setRNConfiguration() or skipPermissionRequests in migrated runtime code.

• Use explicit permission flow. Use checkPermission() only to read status

without prompting; call requestPermission() from a user-understandable app moment before location work needs permission.

• Use Promise APIs for one-shot work. Prefer getCurrentPosition() when the

app needs a fresh position, and getLastKnownPosition() only for cache-first UI where stale data is acceptable.

• Use lifecycle-safe watches. In function components or custom hooks, prefer

useWatchPosition({ enabled }); outside hook-safe code, use watchPosition() with scoped unwatch(token) cleanup.

• Use explicit accuracy presets instead of enableHighAccuracy. Preserve

existing timeout, distance, interval, and cache semantics unless the old code was clearly relying on deprecated defaults.

• Keep permission, provider/settings, and watch cleanup behavior visible in the

code. Do not hide prompts or global cleanup in utility functions unless that is already the app's architecture.

• Use typed errors where handling is specific. Match on

LocationErrorCodes for permission denied, timeout, settings-not-satisfied, or provider/setup failures instead of parsing error messages.

Selection Criteria

Apply these criteria at each call site, in this order:

1. Preserve user-visible behavior first: same trigger, same loading state, same

success/error UI, same cleanup timing.

1. Respect React rules: never introduce hooks in classes, callbacks,

conditionals, loops, services, or non-React modules.

1. Prefer the narrowest lifecycle: hook-managed watch for component state,

token-managed watch for services, one-shot Promise for button/request flows.

1. Prefer explicit user consent: do not convert old implicit permission behavior

into an app-start permission prompt.

1. Prefer battery-aware defaults: only request high accuracy, frequent

intervals, background updates, or settings dialogs when the old code or app feature justifies it.

1. Prefer type-safe function names at module boundaries: avoid passing a

Geolocation object through app code after refactoring.

Use this API choice table:

Import Patterns

The bootstrap script handles this mechanical source rewrite:

import Geolocation from "@react-native-community/geolocation";

to:

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

After verification, refactor compat imports to named imports:

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

Import only the symbols each file needs.

navigator.geolocation usage is reported by the script but not rewritten. It needs manual inspection because it is often a global shim or browser fallback.

API Mappings

getCurrentPosition

Before:

Geolocation.getCurrentPosition(
  (position) => setPosition(position),
  (error) => setError(error),
  { enableHighAccuracy: true, timeout: 15000 }
);

After:

try {
  const position = await getCurrentPosition({
    accuracy: { android: "high", ios: "best" },
    timeout: 15000
  });
  setPosition(position);
} catch (error) {
  setError(error);
}

If the containing function cannot become async, keep the Promise chain:

getCurrentPosition(options).then(onSuccess).catch(onError);

requestAuthorization

Replace requestAuthorization(success?, error?) with requestPermission(). Move success callback behavior after a granted result and move error callback behavior into catch.

const status = await requestPermission();
if (status === "granted") {
  onGranted();
}

setRNConfiguration

Replace setRNConfiguration with setConfiguration at app startup.

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

Do not migrate skipPermissionRequests; there is no equivalent because permission requests must be explicit through requestPermission().

watchPosition in React Components

Use useWatchPosition in function components or custom hooks only. Preserve the old start/stop condition through enabled.

Before:

useEffect(() => {
  const watchId = Geolocation.watchPosition(onPosition, onError, {
    enableHighAccuracy: true,
    distanceFilter: 10
  });
  return () => Geolocation.clearWatch(watchId);
}, []);

After:

const { position, error, isWatching } = useWatchPosition({
  enabled: true,
  accuracy: { android: "high", ios: "best" },
  distanceFilter: 10
});

Wire position, error, and isWatching into the component's existing state or render path. If callbacks perform side effects, add a separate useEffect that reacts to position or error.

watchPosition Outside Hook-Safe Code

Use the low-level watch function outside function component top level:

const token = watchPosition(onPosition, onError, {
  accuracy: { android: "high", ios: "best" },
  distanceFilter: 10
});
unwatch(token);

Replace clearWatch(watchId) with unwatch(token). Keep stopObserving() only when the old code intentionally stopped all geolocation subscriptions; otherwise prefer targeted unwatch(token).

Options