true-link

Tiny zero-config network truth detector. Catches lie-fi, classifies connection strength.

navigator.onLine lies in 30% of cases on mobile. true-link uses fetch-ping with timeout to detect real connectivity, classifies as strong | weak | offline, and catches lie-fi before your users notice.

Zero runtime deps, framework adapters included, SSR-safe.

npm i true-link
# or: yarn add true-link
# or: pnpm add true-link

Quick Start

Minimal flow: import → create → subscribe → get { isOnline, strength, latency }.

import { createTrueLink } from "true-link/vanilla";

const tl = createTrueLink({ pingUrl: "/health" });

const unsub = tl.subscribe((v) => {
    if (!v) return;

    console.log(
        `online=${v.isOnline} strength=${v.strength} latency=${v.latency}ms`
    );
});

// later:
// unsub();
// tl.destroy();

Demo snippet

Use this in a real page (Vite/Parcel/Next). Toggle your network to see it react.

<div id="app" style="padding:16px">
  <pre id="out">loading…</pre>
</div>

<script type="module">
  import { createTrueLink } from "true-link/vanilla";

  const out = document.getElementById("out");
  Object.assign(out.style, {
    padding: "12px 16px",
    font: "14px/1.4 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
    background: "#111",
    color: "#0f0",
    borderRadius: "8px",
  });

  const tl = createTrueLink({ pingUrl: "/favicon.ico" });

  tl.subscribe((v) => {
    if (!v) {
      out.textContent = "SSR / null";
      return;
    }
    out.textContent =
`online:   ${v.isOnline}
strength: ${v.strength}
latency:  ${v.latency ?? "n/a"}ms
checking: ${v.isChecking}`;
  });
</script>

Features

A few concrete, technical reasons it behaves well:

• Catches lie-fi: Ping timeout classifies slow/unstable networks as weak or offline.
• Zero runtime deps: 0 dependencies at runtime (tree-shakeable ESM).
• Connection strength: strong | weak | offline based on latency, not just boolean online/offline.
• SSR-safe: Returns null on server, works with React 18 useSyncExternalStore.

API (short)

Core snapshot fields you'll typically use:

• isOnline — true if strength !== 'offline'
• strength — 'strong' | 'weak' | 'offline'
• latency — ping time in ms, or null if offline/checking
• isChecking — true while ping is in flight

Vanilla store:

• createTrueLink(options) from true-link/vanilla → creates a controller with get(), subscribe(), destroy()

Framework adapters:

• React: useTrueLink from true-link/react
• Vue: useTrueLink from true-link/vue
• Svelte: trueLink from true-link/svelte
• Solid: createTrueLink from true-link/solid
• Angular: TrueLinkDirective from true-link/angular

Full types and signatures: see TypeScript IntelliSense or published dist/*.d.ts files.

Adapter Docs: React • Vue • Svelte • Solid • Angular

Links

FAQ • Common pitfalls • Smoke test • Versioning policy

Support the project

If this library saved you time, please consider supporting the development:

1. Fiat (Cards/PayPal): via Boosty (one-time or monthly).
2. Crypto (USDT/BTC/ETH): view wallet addresses on Telegram.

License

MIT