react-native-reliability

A lightweight, production-ready toolkit that improves stability and observability in React Native apps.

---

Why?

React Native apps fail silently in production for many common reasons:

Problem	This toolkit
Unhandled async errors	safeAsync — wraps promises with timeout & error capture
Component render crashes	ReliabilityErrorBoundary — safe fallback UI + structured logging
Unstable network conditions	useNetworkHealth — detects offline / slow / unstable states
Silent promise rejections	safeAsync — global error callback
Background/foreground issues	useAppLifecycle — lifecycle state tracking
Crash loops	useCrashRecovery — detects repeated crashes on startup

Works with React Native CLI and Expo. Every module is fully independent — adopt only what you need.

---

Installation

# npm
npm install react-native-reliability

# yarn
yarn add react-native-reliability

Optional peer dependencies

Install these only for the modules you use:

# useNetworkHealth
npm install @react-native-community/netinfo

# useCrashRecovery (persistent storage across restarts)
npm install @react-native-async-storage/async-storage

---

Quick Start

import { ReliabilityProvider } from 'react-native-reliability';

export default function App() {
  return (
    <ReliabilityProvider>
      <MyApp />
    </ReliabilityProvider>
  );
}

Individual hooks and components work without the provider using sensible defaults.

---

Modules

1 — Error Boundary

Catches React render-tree crashes and renders a fallback UI.

import { ReliabilityErrorBoundary } from 'react-native-reliability';

<ReliabilityErrorBoundary
  fallback={<Text>Something went wrong. Please restart the app.</Text>}
  onError={(error, info) => {
    // send to crash analytics, record crash, etc.
    logError(error, info.componentStack);
  }}
>
  <App />
</ReliabilityErrorBoundary>

Props

Prop	Type	Description
fallback	React.ReactNode	UI shown when the tree crashes. Renders null if omitted.
onError	(error: Error, info: React.ErrorInfo) => void	Called when a render error is caught.
children	React.ReactNode	The component tree to protect.

---

2 — Network Health Monitor

Detects degraded connectivity without constant polling.

import { useNetworkHealth } from 'react-native-reliability';

const network = useNetworkHealth();

switch (network.status) {
  case 'offline':   /* show offline banner */ break;
  case 'slow':      /* show slow-network warning */ break;
  case 'unstable':  /* retry with backoff */ break;
  case 'healthy':   /* proceed normally */ break;
}

Requires @react-native-community/netinfo. Returns healthy (no-op) without it.

Returned object

Field	Type	Description
status	'healthy' | 'slow' | 'unstable' | 'offline'	Overall network status
isOffline	boolean	No internet connection
isSlow	boolean	High latency detected
isUnstable	boolean	Frequent disconnect/reconnect

---

3 — Safe Async Wrapper

Prevents unhandled promise rejections and adds timeout protection.

import { safeAsync } from 'react-native-reliability';

safeAsync(
  () => fetchUser(userId),
  {
    timeout: 5000,
    onError: (error) => logError(error),
  }
)
  .then(handleUser)
  .catch(handleFetchError);

Options

Option	Type	Default	Description
timeout	number	10000	Milliseconds before a TimeoutError is thrown
onError	(error: Error) => void	—	Called for any error (including timeout)

---

4 — App Lifecycle Monitor

Tracks application foreground / background / inactive state transitions.

import { useAppLifecycle } from 'react-native-reliability';

const lifecycle = useAppLifecycle();

useEffect(() => {
  if (lifecycle.state === 'background') {
    stopNetworkPolling();
    saveUserSession();
  }
  if (lifecycle.state === 'active') {
    resumeNetworkPolling();
  }
}, [lifecycle.state]);

Returned object

Field	Type	Description
state	'active' | 'background' | 'inactive'	Current lifecycle state

---

5 — Crash Recovery Helper

Detects repeated crash loops on startup and lets you recover gracefully.

import { useCrashRecovery, ReliabilityErrorBoundary } from 'react-native-reliability';

function Root() {
  const crash = useCrashRecovery();

  if (crash.hasRecentCrash) {
    return (
      <SafeModeScreen
        crashCount={crash.crashCount}
        onReset={crash.clearCrashHistory}
      />
    );
  }

  return (
    <ReliabilityErrorBoundary onError={crash.recordCrash}>
      <App />
    </ReliabilityErrorBoundary>
  );
}

Requires @react-native-async-storage/async-storage for persistence across restarts.
Falls back to in-memory storage (resets on every restart) when not installed.

Returned object

Field	Type	Description
hasRecentCrash	boolean	true when crashes ≥ crashThreshold within crashWindow
crashCount	number	Number of crashes in the current window
recordCrash	(error?: Error) => Promise<void>	Record a crash event
clearCrashHistory	() => Promise<void>	Clear all stored crash data

---

Provider Configuration

Override defaults globally with ReliabilityProvider:

<ReliabilityProvider
  config={{
    crashWindow: 120_000,          // 2 minute window (default: 60_000)
    crashThreshold: 3,             // crashes to trigger hasRecentCrash (default: 2)
    networkCheckUrl: 'https://api.myapp.com/health',
    slowNetworkThreshold: 3000,    // ms (default: 2000)
    unstableNetworkThreshold: 5,   // disconnects/min (default: 3)
  }}
>
  <App />
</ReliabilityProvider>

All hooks also accept these values from context automatically when wrapped in the provider.

---

Full Production Example

import React from 'react';
import {
  ReliabilityProvider,
  ReliabilityErrorBoundary,
  useNetworkHealth,
  useAppLifecycle,
  useCrashRecovery,
  safeAsync,
} from 'react-native-reliability';

function AppShell() {
  const network = useNetworkHealth();
  const lifecycle = useAppLifecycle();
  const crash = useCrashRecovery();

  // Show safe mode if crash loop detected
  if (crash.hasRecentCrash) {
    return <SafeModeScreen onReset={crash.clearCrashHistory} />;
  }

  return (
    <ReliabilityErrorBoundary
      onError={crash.recordCrash}
      fallback={<ErrorScreen />}
    >
      {network.isOffline && <OfflineBanner />}
      {lifecycle.state === 'active' && <MainApp />}
    </ReliabilityErrorBoundary>
  );
}

export default function App() {
  return (
    <ReliabilityProvider config={{ crashThreshold: 3 }}>
      <AppShell />
    </ReliabilityProvider>
  );
}

---

Design Philosophy

Stability, safety, and predictability — not analytics dashboards.

• Never crashes the host app — all handlers are wrapped in try/catch
• Minimal dependencies — peer deps are optional; modules work independently
• No polling — event-driven where possible; ping on demand
• Strict TypeScript — no any, full type coverage
• Works in dev and production — same API, no build flags

---

Architecture

src/
  core/
    reliabilityProvider.tsx     ← shared config context (optional)
  modules/
    errorBoundary/
      ReliabilityErrorBoundary.tsx
    networkHealth/
      useNetworkHealth.ts
    safeAsync/
      safeAsync.ts
    lifecycle/
      useAppLifecycle.ts
    crashRecovery/
      useCrashRecovery.ts
  hooks/
    useNetworkHealth.ts         ← re-exports
    useAppLifecycle.ts
  types/
    reliabilityTypes.ts
  index.ts

---

License

MIT