Registry / http-networking / offline-detector

offline-detector

library1.1.1jsnpmunverified

offline-detector is a lightweight TypeScript library designed for robustly detecting network online/offline status exclusively within browser environments. Its current stable version is 1.1.1. The library differentiates itself by combining native browser `online`/`offline` events with intelligent network verification through configurable polling, which significantly enhances detection accuracy. It is built to be bundler-agnostic, supporting modern tools like Webpack, Vite, and Rollup, and is tree-shakable for minimal bundle size. Development is active, with recent minor and patch releases introducing features like network polling (v1.1.0) and updating Node.js engine requirements for development/testing (v1.1.1). It provides full TypeScript support, debounced state changes to prevent rapid status fluctuations, and extensive configuration options for customizing network tests and event handling.

http-networking observability

npm install offline-detector

github ↗package ↗

INSTALL

IMPORT

SIG · OFFLINE-DETECTOR

offline-detector

http-networkingjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createOfflineDetector

✓ import { createOfflineDetector } from 'offline-detector';

✗ const { createOfflineDetector } = require('offline-detector');

The library primarily uses ESM imports for modern browser environments. CommonJS require() is not the idiomatic or recommended way.

OfflineDetectorOptions

✓ import type { OfflineDetectorOptions } from 'offline-detector';

✗ import { OfflineDetectorOptions } from 'offline-detector';

This is a TypeScript interface; use `import type` to avoid bundling it as a runtime value, which can cause import errors or increased bundle size.

OfflineDetector

✓ import type { OfflineDetector } from 'offline-detector';

✗ import { OfflineDetector } from 'offline-detector';

This is a TypeScript interface for the return type of `createOfflineDetector`; use `import type` for proper type-only import semantics.

This quickstart initializes the offline detector, starts monitoring network status, and logs changes. It also demonstrates checking the current status and properly stopping/destroying the detector.

import { createOfflineDetector } from 'offline-detector'; const detector = createOfflineDetector({ onOnline: () => console.log('Back online!'), onOffline: () => console.log('Gone offline!'), networkVerification: { enabled: true, url: 'https://check.day.app/status.txt', // Example reliable endpoint requestTimeout: 3000, interval: 30000 } }); // Start monitoring network status detector.start(); // Check current status at any time console.log('Current status:', detector.isOnline() ? 'Online' : 'Offline'); // Simulate stopping after a while (e.g., component unmount) setTimeout(() => { detector.stop(); console.log('Detector stopped.'); detector.destroy(); // Clean up resources }, 10000);

Debug

Known issues

gotchaThis library is designed exclusively for browser environments. Attempting to run it in a Node.js server-side rendering (SSR) context without proper shims or conditional imports will likely result in runtime errors related to browser-specific globals like `window`.

fix

Ensure the `offline-detector` is only imported and executed within client-side browser code or use dynamic imports with `typeof window !== 'undefined'` checks for SSR applications.

affects: >=1.0.0

gotchaThe package specifies a Node.js engine requirement of `>=18.0.0` in its `package.json`. While the library itself is browser-focused, developers building or testing applications that include `offline-detector` should ensure their Node.js environment meets this minimum version to avoid potential issues with build tools or test runners.

fix

Update your Node.js version to 18.0.0 or higher using a version manager like `nvm` or `volta`.

affects: >=1.1.1

gotchaNetwork polling, introduced in v1.1.0, adds robustness but also performs periodic network requests. Be mindful of the `interval`, `requestTimeout`, and `url` configuration for `networkVerification` to avoid excessive network traffic or testing against unreliable endpoints, especially in mobile data environments.

fix

Customize the `networkVerification` options in `createOfflineDetector` to suit your application's needs, adjusting `interval` for less frequent checks and ensuring `url` points to a stable, low-latency endpoint, or disable `enabled` if only native events are desired.

affects: >=1.1.0

Errors

Common errors & fixes

ReferenceError: window is not defined

The library is being executed in a Node.js environment (e.g., during server-side rendering or in a Node.js script) where the global `window` object is not available.

fix

Wrap the `createOfflineDetector` call and other library usages in a conditional block to ensure they only run in a browser: `if (typeof window !== 'undefined') { /* ... library usage ... */ }`. For frameworks like Next.js or Astro, use dynamic imports with `ssr: false`.

TypeError: (0, import_offline_detector.createOfflineDetector) is not a function

This error often occurs in mixed CommonJS/ESM environments when a bundler or runtime incorrectly handles an ESM import that expects named exports as a default export, or vice-versa, or when attempting to `require` an ESM-only package.

fix

Ensure you are using `import { createOfflineDetector } from 'offline-detector';` and that your build setup correctly processes ESM. Avoid `const detector = require('offline-detector');` which is not supported for this module.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hiteshshetty-dev/offline-detector ↗

packagehttps://www.npmjs.com/package/offline-detector ↗