Connectivity

Requires features.connectivity.enabled: true. Without this flag, no connectivity monitoring code is generated.

The connectivity module provides real online/offline detection that goes beyond navigator.onLine — it performs a HEAD heartbeat every 30s to verify actual network reachability.

Preconditions

• Swoff initialized (swoff init done)
• Service worker registered and controlling the page
• features.connectivity.enabled: true in swoff.config.json

Status

Off by default. Enable it explicitly:

{
  "features": {
    "connectivity": {
      "enabled": true,
      "heartbeatIntervalMs": 30000
    }
  }
}

How it works

1. On app init, the client-injector calls verifyAndNotify() — performs a HEAD /{timestamp}?hb=1 with a 5s timeout
2. If the fetch succeeds and navigator.onLine is true, it dispatches app-connectivity-change with { online: true } and notifies the SW via postMessage({ type: "ONLINE" })
3. On failure, it dispatches { online: false } and sends OFFLINE to the SW
4. A setInterval heartbeat runs every 30s (only when the tab is visible) to re-verify
5. On window.online / window.offline events, the heartbeat is restarted/stopped
6. On visibilitychange, the heartbeat verifies when the tab becomes visible, stops when hidden

Generated files

Exports

CONNECTIVITY_EVENT

Constant: "app-connectivity-change". Use this string or the constant to listen for verified connectivity changes.

getCurrentOnlineStatus()

Returns boolean — the last verified online status (synchronous, no fetch needed).

startHeartbeat()

Begins the 30s interval heartbeat. Called automatically by the client-injector. Only runs while the tab is visible (document.hidden check).

stopHeartbeat()

Stops the interval heartbeat. Called automatically on window.offline and visibilitychange (hidden).

verifyAndNotify()

Triggers an immediate HEAD request to verify connectivity, dispatches CONNECTIVITY_EVENT, and posts ONLINE/OFFLINE to the SW controller. Returns Promise<boolean>.

forceRetry()

Stops the heartbeat, calls verifyAndNotify(), then restarts the heartbeat. Useful for retry buttons in your UI.

Window events

Framework adapters

useSwoffNetwork

Exposes connectivity state: { online, wasOffline, lastChangedAt, effectiveType, downlink, isRetrying, retry }.

Uses the generated connectivity.ts module which runs a HEAD heartbeat every 30s to verify true connectivity (not just navigator.onLine). The module must be started at app init via startHeartbeat() — the client-injector does this automatically.

Events listened to:

Imports from connectivity.ts: CONNECTIVITY_EVENT, getCurrentOnlineStatus, forceRetry.

If your framework already has a useSwoffNetwork adapter (React, Vue, Svelte), the CLI generates it into swoff/adapters/. To create adapters for any other framework, see the Blueprint for the event reference and adapter patterns.