Offline Detector

A lightweight TypeScript library for detecting online/offline status in browsers with modern bundler support.

Features

• 🌐 Browser-focused: Designed specifically for browser environments
• 📦 Bundler agnostic: Works with any modern bundler (Webpack, Vite, Rollup, etc.)
• 🔧 TypeScript: Full TypeScript support with type definitions
• 🚀 Lightweight: Minimal bundle size with tree-shaking support
• 📱 Cross-platform: Works across all modern browsers
• 🔍 Smart Detection: Combines native events with network verification
• ⚡ Debounced: Prevents rapid state changes with configurable debouncing
• 🎯 Configurable: Extensive options for customization

Installation

npm install offline-detector

Quick Start

import { createOfflineDetector } from 'offline-detector';

const detector = createOfflineDetector({
  onOnline: () => console.log('Back online!'),
  onOffline: () => console.log('Gone offline!'),
});

// Start monitoring
detector.start();

// Check current status
console.log(detector.isOnline()); // true or false

// Stop monitoring
detector.stop();

Packages

This is a monorepo containing multiple packages:

• offline-detector - Core detection library with comprehensive API documentation
• offline-detector/react - React hooks and components (coming soon)
• offline-detector/vue - Vue composables and components (coming soon)

API Overview

The core API is simple and intuitive:

const detector = createOfflineDetector({
  onOnline: () => console.log('Back online!'),
  onOffline: () => console.log('Gone offline!'),
});

detector.start(); // Start monitoring
detector.isOnline(); // Check current status
detector.stop(); // Stop monitoring
detector.destroy(); // Clean up resources

📖 View complete API documentation →

Advanced Usage

Custom Configuration

const detector = createOfflineDetector({
  onOnline: () => syncPendingData(),
  onOffline: () => showOfflineBanner(),
  stateChangeDebounceDelay: 2000,
  networkVerification: {
    enabled: true,
    url: 'https://api.example.com/health',
    interval: 30000,
    maxFailures: 2,
  },
});

React Integration

function useOfflineDetector() {
  const [isOnline, setIsOnline] = useState(true);

  useEffect(() => {
    const detector = createOfflineDetector({
      onOnline: () => setIsOnline(true),
      onOffline: () => setIsOnline(false),
    });

    detector.start();
    return () => detector.destroy();
  }, []);

  return isOnline;
}

📚 View more examples and detailed configuration →

License

MIT

Security

Security is important to us. If you discover a security vulnerability, please follow our Security Policy for responsible disclosure.

Contributing

See CONTRIBUTING.md for details.

Development

# Install dependencies
npm install

# Start development mode
npm run dev

# Build the library
npm run build

# Run linting
npm run lint

# Format code
npm run format

Roadmap

Phase 1: Core Library

• Repository setup and boilerplate
• TypeScript configuration
• Modern bundler support (Rollup)
• ESLint and Prettier setup
• Basic online/offline detection implementation
• API documentation
• Example website/demo configuration
• Testing framework setup (Jest/Vitest)
• Unit tests and CI/CD

Phase 2: Enhanced Features

• Network quality detection
• Custom polling strategies
• Connection verification with configurable test URLs
• Debounced state changes
• Failure threshold handling
• Connection type detection

Phase 3: Monorepo Migration

• Convert to monorepo structure (Lerna)
• [] Split into multiple packages:
  • offline-detector - Core detection logic
  • offline-detector/react - React hooks and components
  • offline-detector/vue - Vue composables and components
  • offline-detector/svelte - Svelte stores and components
  • offline-detector/angular - Angular services and directives
• Shared tooling and configuration
• Independent versioning and publishing (Changesets)
• Cross-package testing and validation
• Comprehensive testing suite
• Performance benchmarks
• Browser compatibility testing