Installation

Packages

Connectivity is split into two packages:

For React projects, install @connectivity-js/react.

pnpm add @connectivity-js/react

npm install @connectivity-js/react

yarn add @connectivity-js/react

Peer Dependencies

@connectivity-js/react requires:

• react ^18 || ^19

Provider Setup (Recommended: instance-first)

Create a ConnectivityClient instance and pass it to ConnectivityProvider:

import {
  ConnectivityClient,
  ConnectivityProvider,
  browserOnlineDetector,
  heartbeatDetector,
} from "@connectivity-js/react";
 
const client = new ConnectivityClient({
  detectors: [
    browserOnlineDetector(),
    heartbeatDetector({ url: "/api/health" }),
  ],
  gracePeriodMs: 3_000,
});
 
function App() {
  return (
    <ConnectivityProvider client={client}>
      <YourApp />
    </ConnectivityProvider>
  );
}

For testing and Storybook, always use the instance-first pattern so each test/story gets an isolated client.

Quick Start (singleton)

For single-app setups, you can use the detectors prop directly. This uses getConnectivityClient() internally — a convenience singleton that applies only the first caller’s options (subsequent calls ignore options).

import {
  ConnectivityProvider,
  browserOnlineDetector,
  heartbeatDetector,
} from "@connectivity-js/react";
 
function App() {
  return (
    <ConnectivityProvider
      detectors={[
        browserOnlineDetector(),
        heartbeatDetector({ url: "/api/health" }),
      ]}
      gracePeriodMs={3_000}
      defaultOptions={{
        actions: { whenOffline: "queue" },
      }}
    >
      <YourApp />
    </ConnectivityProvider>
  );
}

detectors

Pluggable strategies for determining network status. Combine multiple for reliability:

• browserOnlineDetector() — Uses navigator.onLine + browser events. Fast but cannot detect “LAN connected, no internet” scenarios.
• heartbeatDetector({ url }) — Periodic HEAD requests to verify actual connectivity. Also measures RTT.

Using both together: browserOnlineDetector reacts instantly, while heartbeatDetector verifies the real connection.

gracePeriodMs

Suppresses state transitions on brief disconnections. If connectivity recovers within this window, the offline transition is ignored entirely. See Grace Period.

defaultOptions

Global defaults applied to all useAction calls and <Connectivity> components. See Default Options.

DevTools (Optional)

For a debugging DevTools panel:

• React: @connectivity-js/react-devtools
• Vanilla JS: @connectivity-js/devtools

See DevTools for details.

Using Without React

If you are not using React, you can use @connectivity-js/core directly:

pnpm add @connectivity-js/core

npm install @connectivity-js/core

yarn add @connectivity-js/core

See Vanilla JS for usage without React.

Next Steps

• Connectivity UI — Display online/offline state with <Connectivity>, useConnectivity
• Actions — Define and execute your first action