TrueLink

Appearance

npm / Installation ​

This page is the "package-level" entry point: how to install true-link, what it exports, which runtimes are supported, and what to do when installation or bundling goes sideways.

Install ​

Choose your package manager:

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

Requirements ​

  1. Node.js: 18+ (LTS and newer)
  2. TypeScript: supported (types are included)
  3. Runtime: browser-first (uses fetch + AbortController)

Tip: If you target older browsers, ensure fetch and AbortController are available (or polyfilled).

What this package exports ​

true-link is split into small entry points so bundlers can tree-shake effectively.

Common patterns you'll see in this repo's docs:

  • React: useTrueLink(...)
  • Vue: useTrueLink(...)
  • Svelte: trueLink(...)
  • Solid: createTrueLink(...)
  • Angular: TrueLinkDirective

If your project uses SSR (Next.js/Nuxt/etc.), make sure network-dependent code runs on the client (e.g. in effects / mounted hooks). The framework adapters in the docs follow that pattern.

Peer dependencies (framework adapters) ​

Framework integrations typically rely on your framework being installed in your app.

If you're using:

  • React → you already have react installed
  • Vue → you already have vue installed
  • Svelte → you already have svelte installed
  • Solid → you already have solid-js installed
  • Angular → you already have @angular/* installed

If your package manager warns about peer deps, it's usually safe: it just means the adapter expects your app to provide the framework.

Upgrading ​

bash
npm update true-link

For bigger upgrades, check:

  • GitHub Releases / tags
  • Changelog (if present)

Troubleshooting ​

1) "Cannot find module …" / missing exports ​

Ensure you're importing from the correct entry point shown in the docs (React/Vue/Svelte/etc.).

Clear lockfile + reinstall if your environment is stale:

bash
rm -rf node_modules package-lock.json
npm i

(Use the equivalent for pnpm/yarn.)

2) SSR errors like "window is not defined" ​

This is expected if you call network APIs during SSR.

Fix: run network-dependent code only on the client:

  • React: useEffect
  • Vue: onMounted
  • Svelte: onMount
  • Solid: onMount
  • Angular: after view init / directive lifecycle hooks

3) Ping returns 200 but strength is "weak" ​

This is normal. true-link measures latency. If the ping takes longer than weakLatencyMs (default 2000ms), it classifies the connection as "weak" even if the HTTP status is 200.