react-native-local-network-info 1.0.0

package/src/LocalNetworkInfo.types.ts

@@ -0,0 +1,110 @@
+/**
+ * Which network role is currently providing the device's local IPv4.
+ *
+ * - `wifi`    — the device is connected to a WiFi network as a station/client.
+ * - `hotspot` — the device is acting as a WiFi hotspot (SoftAP) host.
+ * - `none`    — neither WiFi nor hotspot is providing a usable LAN address
+ *               (e.g. cellular-only, airplane mode, or offline).
+ *
+ * When both WiFi and hotspot are active simultaneously, `wifi` takes precedence.
+ */
+export type NetworkRole = 'wifi' | 'hotspot' | 'none';
+
+/** The platform that produced a given snapshot. */
+export type DevicePlatform = 'ios' | 'android' | 'web';
+
+/**
+ * The usable host range of the hotspot subnet — i.e. the addresses a client
+ * could be assigned. This is the whole subnet's usable span (network+1 ..
+ * broadcast-1), so the host/gateway itself is one address *within* this range
+ * (it is not a boundary). When scanning for clients, skip your own `ip`.
+ *
+ * Example: host/gateway `10.121.184.216` on a `/24` → range `10.121.184.1` ..
+ * `10.121.184.254` (a client may legitimately be `.215` *or* `.217`).
+ */
+export interface ClientIpRange {
+  /** First usable client IPv4 in the subnet. */
+  first: string;
+  /** Last usable client IPv4 in the subnet. */
+  last: string;
+}
+
+/**
+ * A point-in-time snapshot of the device's local network position.
+ *
+ * The same shape is returned by {@link getLocalIp} and delivered to
+ * {@link addNetworkChangeListener} / {@link useLocalIp}.
+ */
+export interface LocalIpInfo {
+  /**
+   * The device's own local IPv4 on the active LAN interface, or `null` when
+   * there is no WiFi/hotspot LAN address. Follows the precedence:
+   * WiFi station IP first, then hotspot host IP.
+   */
+  ip: string | null;
+
+  /** Which role is providing {@link ip}. WiFi takes precedence over hotspot. */
+  role: NetworkRole;
+
+  /** `true` when connected to a WiFi network as a client/station. */
+  isWifiConnected: boolean;
+
+  /** `true` when this device is currently acting as a WiFi hotspot (SoftAP) host. */
+  isHotspotHost: boolean;
+
+  /**
+   * Name of the network interface backing {@link ip}
+   * (e.g. `en0`, `wlan0`, `bridge100`, `ap0`), or `null`.
+   */
+  interfaceName: string | null;
+
+  /** Dotted IPv4 subnet mask for {@link ip} (e.g. `255.255.255.0`), or `null`. */
+  netmask: string | null;
+
+  /**
+   * The LAN gateway.
+   *
+   * - As a **hotspot host**, this is the device itself (it *is* the gateway).
+   * - As an **Android station**, this is the real default-route gateway
+   *   (read from `LinkProperties`).
+   * - As an **iOS station**, this is a best-effort guess derived from the
+   *   subnet (the first host address), because Apple exposes no public gateway
+   *   API. Treat the iOS station gateway as a heuristic.
+   */
+  gateway: string | null;
+
+  /**
+   * When this device is a hotspot host, the predicted inclusive range of IPs
+   * its clients can receive, derived from the host IP + subnet:
+   *
+   * - **iOS** — the fixed Personal Hotspot range `172.20.10.2`–`172.20.10.14`.
+   * - **Android** — computed from the (randomized on Android 11+) SoftAP subnet.
+   *
+   * `null` when the device is not a hotspot host.
+   */
+  predictedClientRange: ClientIpRange | null;
+
+  /** Platform that captured this snapshot. */
+  platform: DevicePlatform;
+
+  /** Epoch milliseconds when this snapshot was captured natively. */
+  timestamp: number;
+}
+
+/** Per-interface detail, returned by {@link getAllInterfaces} for debugging. */
+export interface NetworkInterfaceInfo {
+  /** Interface name (e.g. `en0`, `wlan0`, `bridge100`, `ap0`, `pdp_ip0`). */
+  name: string;
+  /** The interface's IPv4 address. */
+  ip: string;
+  /** Dotted IPv4 subnet mask, when known. */
+  netmask: string | null;
+  /** Best-effort role classification of the interface. */
+  role: 'wifi' | 'hotspot' | 'cellular' | 'ethernet' | 'other';
+}
+
+/** Native event map for the module. */
+export type LocalNetworkInfoModuleEvents = {
+  /** Fired whenever the device's network position changes. */
+  onNetworkChange: (info: LocalIpInfo) => void;
+};

package/src/LocalNetworkInfoModule.ts

@@ -0,0 +1,17 @@
+import { NativeModule, requireNativeModule } from 'expo';
+
+import {
+  LocalNetworkInfoModuleEvents,
+  LocalIpInfo,
+  NetworkInterfaceInfo,
+} from './LocalNetworkInfo.types';
+
+declare class LocalNetworkInfoModule extends NativeModule<LocalNetworkInfoModuleEvents> {
+  /** Capture the current local-IP/network-role snapshot. */
+  getLocalIpAsync(): Promise<LocalIpInfo>;
+  /** Enumerate all up, non-loopback IPv4 interfaces (for debugging/inspection). */
+  getAllInterfacesAsync(): Promise<NetworkInterfaceInfo[]>;
+}
+
+// The string must match `Name("LocalNetworkInfo")` in the Swift/Kotlin modules.
+export default requireNativeModule<LocalNetworkInfoModule>('LocalNetworkInfo');

package/src/LocalNetworkInfoModule.web.ts

@@ -0,0 +1,35 @@
+import { registerWebModule, NativeModule } from 'expo';
+
+import {
+  LocalNetworkInfoModuleEvents,
+  LocalIpInfo,
+  NetworkInterfaceInfo,
+} from './LocalNetworkInfo.types';
+
+/**
+ * Web fallback. Browsers do not expose the device's local LAN IPv4, so this
+ * reports `role: 'none'` with a `null` IP. It exists so the package imports
+ * cleanly on web (Metro resolves `*.web.ts`) and the API surface stays stable.
+ */
+class LocalNetworkInfoModule extends NativeModule<LocalNetworkInfoModuleEvents> {
+  async getLocalIpAsync(): Promise<LocalIpInfo> {
+    return {
+      ip: null,
+      role: 'none',
+      isWifiConnected: false,
+      isHotspotHost: false,
+      interfaceName: null,
+      netmask: null,
+      gateway: null,
+      predictedClientRange: null,
+      platform: 'web',
+      timestamp: Date.now(),
+    };
+  }
+
+  async getAllInterfacesAsync(): Promise<NetworkInterfaceInfo[]> {
+    return [];
+  }
+}
+
+export default registerWebModule(LocalNetworkInfoModule, 'LocalNetworkInfoModule');

package/src/index.ts

@@ -0,0 +1,57 @@
+import { EventSubscription } from 'expo-modules-core';
+
+import LocalNetworkInfoModule from './LocalNetworkInfoModule';
+import { LocalIpInfo, NetworkInterfaceInfo } from './LocalNetworkInfo.types';
+
+/**
+ * Capture the device's current local-IP / network-role snapshot.
+ *
+ * Resolves with WiFi-station info when connected to WiFi; otherwise hotspot-host
+ * info when the device is sharing its connection; otherwise `role: 'none'`.
+ *
+ * @example
+ * ```ts
+ * const info = await getLocalIp();
+ * if (info.role === 'wifi') console.log('On WiFi at', info.ip);
+ * if (info.role === 'hotspot') console.log('Hotspot host at', info.ip);
+ * ```
+ */
+export async function getLocalIp(): Promise<LocalIpInfo> {
+  return LocalNetworkInfoModule.getLocalIpAsync();
+}
+
+/**
+ * Enumerate every up, non-loopback IPv4 interface with a best-effort role
+ * classification. Useful for debugging odd devices/vendors.
+ */
+export async function getAllInterfaces(): Promise<NetworkInterfaceInfo[]> {
+  return LocalNetworkInfoModule.getAllInterfacesAsync();
+}
+
+/**
+ * Subscribe to network changes. The listener fires with a fresh
+ * {@link LocalIpInfo} whenever connectivity, WiFi, or hotspot state changes.
+ *
+ * Remember to call `.remove()` on the returned subscription to avoid leaks
+ * (or use {@link useLocalIp}, which manages this for you).
+ *
+ * @example
+ * ```ts
+ * const sub = addNetworkChangeListener((info) => {
+ *   console.log('network changed →', info.role, info.ip);
+ * });
+ * // later
+ * sub.remove();
+ * ```
+ */
+export function addNetworkChangeListener(
+  listener: (info: LocalIpInfo) => void
+): EventSubscription {
+  return LocalNetworkInfoModule.addListener('onNetworkChange', listener);
+}
+
+/** The raw native module instance (advanced use). */
+export { default as LocalNetworkInfoModule } from './LocalNetworkInfoModule';
+
+export { useLocalIp } from './useLocalIp';
+export * from './LocalNetworkInfo.types';

package/src/useLocalIp.ts

@@ -0,0 +1,50 @@
+import { useEffect, useState } from 'react';
+
+import LocalNetworkInfoModule from './LocalNetworkInfoModule';
+import { LocalIpInfo } from './LocalNetworkInfo.types';
+
+/**
+ * React hook that returns the latest {@link LocalIpInfo} and keeps it updated as
+ * the network changes.
+ *
+ * It captures an initial snapshot on mount and then subscribes to native
+ * `onNetworkChange` events, cleaning up the subscription on unmount.
+ *
+ * @returns the latest snapshot, or `null` until the first snapshot resolves.
+ *
+ * @example
+ * ```tsx
+ * const info = useLocalIp();
+ * return <Text>{info?.ip ?? 'detecting…'} ({info?.role})</Text>;
+ * ```
+ */
+export function useLocalIp(): LocalIpInfo | null {
+  const [info, setInfo] = useState<LocalIpInfo | null>(null);
+
+  useEffect(() => {
+    let mounted = true;
+
+    LocalNetworkInfoModule.getLocalIpAsync()
+      .then((snapshot) => {
+        if (mounted) {
+          setInfo(snapshot);
+        }
+      })
+      .catch(() => {
+        // Swallow — a change event or a later manual refresh will populate it.
+      });
+
+    const subscription = LocalNetworkInfoModule.addListener('onNetworkChange', (snapshot) => {
+      if (mounted) {
+        setInfo(snapshot);
+      }
+    });
+
+    return () => {
+      mounted = false;
+      subscription.remove();
+    };
+  }, []);
+
+  return info;
+}