Quick start

InstallCopy Anchor Link

npm i @net-watch/core

For a framework adapter, install it next to core: @net-watch/react, @net-watch/vue or @net-watch/angular.

Create a watcherCopy Anchor Link

Create one watcher for the whole app and keep it in a module.

import { createNetworkWatcher } from '@net-watch/core'

export const watcher = createNetworkWatcher({
  pingUrl: '/api/ping', // optional: lets net-watch confirm the user can really reach your server
})

Without pingUrl, net-watch still reacts when the browser reports that the network is gone, and it treats a successful request as proof that you are online. It cannot confirm a failed request, so "connected to Wi-Fi but no internet" goes unnoticed. The ping endpoint guide shows how to add one in a few lines.

Read the stateCopy Anchor Link

const { online, quality, rtt } = watcher.getState()

const stop = watcher.subscribe((state, previous) => {
  if (!state.online) console.log('offline since', new Date(state.since))
})
// later: stop()

getState() returns the same object until something changes, so it is safe to use with useSyncExternalStore and signals.

Measure with your real requestsCopy Anchor Link

Wrap fetch once. Every response becomes a free latency sample, and a network error makes net-watch check the connection.

import { watchFetch } from '@net-watch/core/fetch'
import { watcher } from './network'

export const api = watchFetch(watcher)

const res = await api('/api/projects') // use it like fetch

Show a bannerCopy Anchor Link

import { createBanner } from '@net-watch/core/banner'
import { watcher } from './network'

createBanner(watcher, { slowText: 'Slow connection' })

The banner appears when the user goes offline, shows a message while the connection is poor, and, after a loss of connection, says "Back online" for a few seconds. See the banner guide for text, position and theming.