capacitor-offline

A minimal, production-grade Capacitor plugin that automatically handles offline URL routing based on internet connectivity.

Features

• 🔌 Automatic Offline Detection: Checks for internet connectivity once on app startup
• 🏠 Smart URL Routing: Loads local offline content when no internet is available
• 📱 Cross-Platform: Works on both Android (Kotlin) and iOS (Swift)
• ⚡ Zero Configuration: Just add the plugin and configure your capacitor.config.json
• 🎯 Lightweight: Minimal overhead with efficient network checking

Install

npm install capacitor-offline
npx cap sync

Configuration

Add the server.offline property to your capacitor.config.json:

{
  "appId": "com.rqeim.app",
  "appName": "Rqeim",
  "webDir": "dist",
  "server": {
    "url": "https://app.rqeim.com"
  },
  "plugins": {
    "CapOffline": {
      "offlinePath": "index.html"
    }
  }
}

How it Works

1. On App Launch: The plugin checks for internet connectivity once
2. Internet Available: Loads the normal server.url
3. No Internet: Automatically loads schema://localhost/ + server.offline path
4. Native Implementation: Uses ConnectivityManager on Android and NWPathMonitor on iOS

API

checkConnection()

import { CapOffline } from 'capacitor-offline';

const checkNetwork = async () => {
  const result = await CapOffline.checkConnection();
  console.log('Online:', result.online);
};

Returns: Promise<{ online: boolean }>

Optional method for manual connectivity checking (useful for debugging).

Platform Implementation

Android (Kotlin)

• Uses ConnectivityManager with NetworkCapabilities
• Loads URLs via bridge.webView.loadUrl()
• Runs network check in load() lifecycle method

iOS (Swift)

• Uses NWPathMonitor for network detection
• Loads URLs via bridge.webView.load(_:)
• Executes check once during plugin initialization

Example Use Cases

• Progressive Web Apps: Serve cached content when offline
• Hybrid Apps: Fallback to local assets during network issues
• Enterprise Apps: Ensure functionality during connectivity problems

Requirements

• Capacitor: 7.0.0+
• iOS: 14.0+
• Android: API 23+

License

MIT