@imamasari1/react-native-server-down

A premium, highly customizable React Native library to handle Server Down, Internal Server Error (500), and Offline states gracefully. It features a beautiful BottomSheet UI, automatic Axios interceptors, and smart incident tracking.

✨ Features

• 🚀 Automated Interceptor: Seamlessly integrates with Axios to detect 5xx errors and network timeouts.
• 🎨 Premium UI: Beautiful, interactive BottomSheet with smooth animations and customizable themes.
• 🌐 Offline Detection: Real-time monitoring of network connectivity using @react-native-community/netinfo.
• 🔄 Smart Retry: Remembers the last failed request and allows users to "Try Again" with a single tap.
• 🎯 Incident Tracking: Smartly handles repeated errors and prevents annoying popups while maintaining consistency across platforms.
• 🛠 Highly Customizable: Override titles, messages, images, colors, and behavior for every error state.

📦 Installation

npm install @imamasari1/react-native-server-down

Peer Dependencies

This library requires @react-native-community/netinfo and react-native-modal. If you haven't installed them yet:

npm install @react-native-community/netinfo react-native-modal
npx pod-install # For iOS

🚀 Quick Start

1. Setup the Provider

Wrap your application with the ServerStatusProvider. This will manage the global state and display the BottomSheet when needed.

import { ServerStatusProvider } from '@imamasari1/react-native-server-down';

const App = () => {
  return (
    <ServerStatusProvider
      bottomSheetProps={{
        primaryColor: '#0066cc',
        tryAgainText: 'Try Again',
      }}
      serverErrorProps={{
        title: 'Technical Difficulty',
        message: "We're experiencing a technical issue.\nOur team is already on the case.",
      }}
    >
      <YourAppNavigator />
    </ServerStatusProvider>
  );
};

2. Attach Axios Interceptor

Automatically trigger the error state when your API calls fail.

import axios from 'axios';
import { attachServerStatusInterceptor } from '@imamasari1/react-native-server-down';

const apiClient = axios.create({ baseURL: 'https://api.yoursite.com' });

attachServerStatusInterceptor(apiClient, {
  notifyOn5xx: true,
  // Optional: Custom logic to identify network errors/timeouts
  isNetworkError: (error) => error.code === 'ECONNABORTED' || error.message.includes('timeout')
});

🔧 Customization Options

ServerStatusProvider Props

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | enabled | boolean | true | Enable or disable the global handler. | | bottomSheetProps | Object | {} | Base props for the BottomSheet (colors, buttons, etc). | | serverErrorProps | Object | {} | Custom text/image for 500 errors. | | serverDownProps | Object | {} | Custom text/image for 501-599 errors. | | offlineProps | Object | {} | Custom text/image for connectivity issues. | | showOn | Array | ['server_down', 'offline', 'server_error'] | Which states should trigger the UI. |

🎣 Hooks

You can access the current status programmatically using the useServerStatusContext or useServerStatus hook.

import { useServerStatusContext } from '@imamasari1/react-native-server-down';

const MyComponent = () => {
  const { status, isChecking, retry } = useServerStatusContext();

  return (
    <View>
      <Text>Current Status: {status.type}</Text>
      {isChecking && <ActivityIndicator />}
      <Button title="Manual Retry" onPress={retry} />
    </View>
  );
};

📜 License

MIT © imambawana