# link-check

> checks whether a hyperlink is alive (200 OK) or dead

Latest version **5.6.0** (published 2026-07-28) · ISC license · 0 weekly downloads

## Install

```sh
npm install link-check
pnpm add link-check
yarn add link-check
bun add link-check
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 5.6.0 |
| Published | 2026-07-28 |
| First published | 2016-01-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 18.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 48 |
| Author | Thomas Cort |
| Maintainers | tcort |
| Keywords | link, check, checker, hyperlink, alive, dead, HTTP, head |

## Links

- npm: https://www.npmjs.com/package/link-check
- Repository: https://github.com/tcort/link-check
- Homepage: https://github.com/tcort/link-check#readme
- Issues: https://github.com/tcort/link-check/issues
- npm.io page: https://npm.io/package/link-check

## Dependencies (5)

- [ms](https://npm.io/package/ms.md) ^2.1.3
- [needle](https://npm.io/package/needle.md) ^3.5.0
- [proxy-agent](https://npm.io/package/proxy-agent.md) ^8.0.2
- [is-relative-url](https://npm.io/package/is-relative-url.md) ^4.1.0
- [node-email-verifier](https://npm.io/package/node-email-verifier.md) ^4.0.0

## Recent versions

- 5.6.0 (latest) — 2026-07-28
- 5.5.1 — 2025-11-19
- 5.5.0 — 2025-09-17
- 5.4.0 — 2024-11-05
- 5.3.0 — 2024-03-10
- 5.2.0 — 2022-09-21
- 5.1.0 — 2022-03-19
- 5.0.3 — 2022-03-19
- 5.0.2 — 2022-01-21
- 5.0.1 — 2021-11-24
- 5.0.0 — 2021-05-25
- 4.5.4 — 2020-12-09
- 3.8.5 — 2020-12-09
- 4.5.3 — 2020-12-05
- 4.5.2 — 2020-10-07
- … 29 more at https://npm.io/package/link-check/versions

## README

![Test library](https://github.com/tcort/link-check/actions/workflows/ci.yml/badge.svg)

# link-check

Checks whether a hyperlink is alive (`200 OK`) or dead.

## Installation

```console
npm install --save link-check
```

## Specification

A link is said to be 'alive' if an HTTP HEAD or HTTP GET for the given URL
eventually ends in a `200 OK` response. To minimize bandwidth, an HTTP HEAD
is performed. If that fails (e.g. with a `405 Method Not Allowed`), an HTTP
GET is performed. Redirects are followed.

In the case of `mailto:` links, this module validates the e-mail address using
[node-email-verifier](https://www.npmjs.com/package/node-email-verifier).

## API

### linkCheck(link, [opts,] callback)

Given a `link` and a `callback`, attempt an HTTP HEAD and possibly an HTTP GET.

Parameters:

* `url` string containing a URL.
* `opts` optional options object containing any of the following optional fields:
  * `anchors` array of anchor strings (e.g. `[ "#foo", "#bar" ]`) for checking anchor links (e.g. `<a href="#foo">Foo</a>`).
  * `baseUrl` the base URL for relative links.
  * `timeout` timeout in [zeit/ms](https://www.npmjs.com/package/ms) format. (e.g. `"2000ms"`, `20s`, `1m`). Default `10s`.
  * `user_agent` the user-agent string. Default `${name}/${version}` (e.g. `link-check/4.5.5`)
  * `aliveStatusCodes` an array of numeric HTTP Response codes which indicate that the link is alive. Entries in this array may also be regular expressions. Example: `[ 200, /^[45][0-9]{2}$/ ]`.  Default `[ 200 ]`.
  * `headers` a string based attribute value object to send custom HTTP headers. Example: `{ 'Authorization' : 'Basic Zm9vOmJhcg==' }`.
  * `retryOn429` a boolean indicating whether to retry on a 429 (Too Many Requests) response. When true, if the response has a 429 HTTP code and includes an optional `retry-after` header, a retry will be attempted after the delay indicated in the `retry-after` header. If no `retry-after` header is present in the response or the `retry-after` header value is not valid according to [RFC7231](https://tools.ietf.org/html/rfc7231#section-7.1.3) (value must be in seconds), a default retry delay of 60 seconds will apply. This default can be overriden by the `fallbackRetryDelay` parameter.
  * `retryCount` the number of retries to be made on a 429 response. Default `2`.
  * `fallbackRetryDelay` the delay in [zeit/ms](https://www.npmjs.com/package/ms) format. (e.g. `"2000ms"`, `20s`, `1m`) for retries on a 429 response when no `retry-after` header is returned or when it has an invalid value. Default is `60s`.
* `callback` function which accepts `(err, result)`.
  * `err` an Error object when the operation cannot be completed, otherwise `null`.
  * `result` an object with the following properties:
    * `link` the `link` provided as input
    * `status` a string set to either `alive` or `dead`.
    * `statusCode` the HTTP status code. Set to `0` if no HTTP status code was returned (e.g. when the server is down).
    * `err` any connection error that occurred, otherwise `null`.

## Examples

```js
'use strict';

import linkCheck from 'link-check';

linkCheck('http://example.com', function (err, result) {
    if (err) {
        console.error(err);
        return;
    }
    console.log(`${result.link} is ${result.status}`);
});
```

**With basic authentication:**

```js
'use strict';

import linkCheck from 'link-check';

linkCheck('http://example.com', { headers: { 'Authorization': 'Basic Zm9vOmJhcg==' } }, function (err, result) {
    if (err) {
        console.error(err);
        return;
    }
    console.log(`${result.link} is ${result.status}`);
});
```

## Testing

```console
npm test
```

## License

See [LICENSE.md](https://github.com/tcort/link-check/blob/master/LICENSE.md)

---
_Source: https://npm.io/package/link-check · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._