link-exists

npm downloads per month GitHub stars

GitHub repository · npm package

A super lightweight JavaScript / TypeScript library to check whether a given url is valid and exists or not.

Install

npm install link-exists

Requires Node.js 18 or newer.

API

linkExists(link: string, config?: LinkValidatorConfig): Promise<boolean | LinkCheckResult>

Throws TypeError only if link is not a string or a config field has the wrong type. Network problems return false (or a failure object when details: true).

Config options

Field Type Default What it does
ignoreProtocol boolean false If true, links without http:// or https:// are still checked (protocol is added).
timeout number (ms) none Stops the request after this many milliseconds. 0 or omitted means no timeout.
method 'HEAD' | 'GET' 'HEAD' HTTP method for the first request. With default HEAD, a failed HEAD can fall back to GET unless you turn that off.
fallbackToGet boolean true When using HEAD first, retry with GET if HEAD fails (network error). Set false to skip the GET retry.
details boolean false If true, returns an object with exists, status, url instead of a boolean. exists follows Response.ok (good status range).

Return values

Default (details off or false)

Promise<boolean> — true if a response was received (any normal HTTP status). false for bad URLs, timeouts, missing fetch, or network failure.

Detailed (details: true)

Promise<LinkCheckResult>:

interface LinkCheckResult {
  exists: boolean;  // same idea as response.ok
  status: number;   // HTTP status, or 0 when there is no response
  url: string;      // final response URL, or your URL string on failure
}

Behavior notes

TypeScript examples

Import the module and use the linkExists function. Here are some code examples.

Simple check

import { linkExists } from 'link-exists';

const ok = await linkExists('https://example.com');
console.log(ok);
$ node app.js
true

Detailed result

import { linkExists } from 'link-exists';

const info = await linkExists('https://example.com', { details: true });
console.log(JSON.stringify(info, null, 2));
$ node app.js
{
  "exists": true,
  "status": 200,
  "url": "https://example.com/"
}

Timeout and method

const ok = await linkExists('https://example.com', {
  timeout: 5000,
  method: 'GET',
});
console.log(ok);
$ node app.js
true

Host-only or www. strings with no http:// or https:// return false by default. Use a full URL or set ignoreProtocol: true so http:// is added.

Host or www without a scheme (default)

import { linkExists } from 'link-exists';

const ok = await linkExists('www.stackblogger.com');
console.log(ok);
$ node app.js
false

Same host with ignoreProtocol

import { linkExists } from 'link-exists';

const ok = await linkExists('www.stackblogger.com', { ignoreProtocol: true });
console.log(ok);
$ node app.js
true

Bare domain with ignoreProtocol

const ok = await linkExists('example.com', { ignoreProtocol: true });
console.log(ok);
$ node app.js
true

JavaScript examples

Require the module and use the linkExists function. Below shows typical terminal output.

Require and run

const { linkExists } = require('link-exists');

(async () => {
  const ok = await linkExists('https://example.com');
  console.log(ok);
})();
$ node app.js
true

Host-only or www. without a scheme returns false unless you pass ignoreProtocol: true or use a full URL.

Host or www without a scheme (default)

const { linkExists } = require('link-exists');
(async () => {
  console.log(await linkExists('www.stackblogger.com'));
})();
$ node app.js
false

Same host with ignoreProtocol

const { linkExists } = require('link-exists');
(async () => {
  console.log(await linkExists('www.stackblogger.com', { ignoreProtocol: true }));
})();
$ node app.js
true

Failure in CLI (boolean mode)

const { linkExists } = require('link-exists');
(async () => {
  console.log(await linkExists('https://this-host-should-not-resolve.test/'));
})();
$ node app.js
false

Detailed failure shape

const { linkExists } = require('link-exists');
(async () => {
  const r = await linkExists('not a real url .com', { details: true });
  console.log(JSON.stringify(r));
})();
$ node app.js
{"exists":false,"status":0,"url":"not a real url .com"}