React Server Status Handler

A robust, enterprise-grade React utility designed to gracefully manage server disruptions, internal errors (500), and connectivity issues. Built to ensure a seamless user experience through intelligent incident detection and automated UI feedback.

Key Capabilities

• 🛡️ Proactive Error Interception: Seamless integration with Axios to automatically capture and handle 5xx server errors and network timeouts.
• 🚦 Intelligent Polling Engine: A high-efficiency background health-check system with configurable intervals and exponential backoff to reduce server load during outages.
• ⏱️ Stabilized Initialization: Includes a configurable 30-second initialization delay to prevent network congestion during application startup.
• 📡 Real-time Connectivity Guard: Instant detection of offline states with automatic UI synchronization.
• ✨ Premium UI Integration: Native support for SweetAlert2 with built-in, context-aware illustrations for different error states.
• 🔒 Singleton Execution: Guaranteed single-instance polling execution, preventing redundant network requests even during rapid component re-renders.

Installation

npm install @imamasari1/react-js-server-down-handler sweetalert2

Quick Start

1. Configure the Provider

Wrap your application at the root level to enable global status tracking.

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

const AppConfig = {
  healthCheckUrl: 'https://api.yourdomain.com/v1/health',
  interval: 60000,      // 1 minute (Standard)
  downInterval: 15000,  // 15 seconds (During incident)
};

function Root() {
  return (
    <ServerStatusProvider polling={AppConfig}>
      <YourAppContent />
    </ServerStatusProvider>
  );
}

2. Connect Axios

Attach the global interceptor to your Axios instance to automate error detection.

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

// Attach to global axios or a specific instance
attachServerStatusInterceptor(axios);

Advanced Customization

The ServerStatusProvider accepts several props to tailor the visual experience:

| Prop | Type | Description | | :--- | :--- | :--- | | polling | PollingConfig | Configuration for health checks and retry intervals. | | swalDefaults | SweetAlertOptions | Override default SweetAlert2 global settings. | | serverErrorProps | AlertContent | Custom text and images for 500 Internal Server Errors. | | serverDownProps | AlertContent | Custom text and images for 502/503/504 Service Down states. | | offlineProps | AlertContent | Custom text and images for network connectivity loss. | | illustrationImage | string | (Inside AlertContent) Override the default illustration with a custom URL. |

Default Illustrations

The package now includes high-quality default illustrations for:

• Offline: Network connectivity issues.
• Server Down: Unreachable or timed-out server.
• Server Error: 5xx Internal Server errors.

You can override these globally or per-state using the illustrationImage prop within serverErrorProps, serverDownProps, or offlineProps.

Tutorial: Customizing Illustrations

1. Basic Usage (Auto-detect)

By default, the library automatically picks the correct illustration based on the error type detected by the Axios interceptor or polling engine. You don't need to do anything!

2. Overriding Globally via Provider

If you want to use a specific image for a certain error type across your entire app:

<ServerStatusProvider
  serverErrorProps={{
    title: "System Maintenance",
    illustrationImage: "https://yourdomain.com/assets/error-500.png"
  }}
  offlineProps={{
    title: "No Internet",
    illustrationImage: "https://yourdomain.com/assets/offline.png"
  }}
>
  <App />
</ServerStatusProvider>

3. Using the ServerDown Component Manually

If you are building a custom error page and want to use the built-in component with specific illustrations:

import { ServerDown } from '@imamasari1/react-js-server-down-handler';

// Option A: Use built-in variant defaults
<ServerDown variant="server_down" title="Oops! Service Down" />

// Option B: Pass a custom image URL
<ServerDown illustrationImage="https://example.com/custom-down.png" />

// Option C: Pass a React Node (SVG/Icon)
<ServerDown illustrationImage={<MyCustomIcon />} />

Technical Considerations

Target Compatibility

This package is transpiled to ES2018 to ensure full compatibility with legacy build systems (e.g., Webpack 4) while maintaining performance in modern browsers.

Polling Stabilization

The engine implements a 30-second "warm-up" period. Polling will only commence 30 seconds after the Provider is instantiated to ensure core application assets and authentication flows take priority.

License

MIT © Imam Asari