astro-link-checker

Fast intra-site broken link checker for Astro. Runs after astro build and reports any href values that don't resolve to a real file in the build output.

External links are not checked. For those, point a tool like lychee at your deployed site.

Why faster

The common approach checks links per-file: if /docs/get-started is linked from 400 pages, it gets stat'd 400 times. This plugin deduplicates first, checking every unique destination exactly once regardless of how many pages reference it. File reads and existence checks all run in parallel.

Installation

npm install astro-link-checker

Usage

// astro.config.ts
import { defineConfig } from 'astro/config';
import linkChecker from 'astro-link-checker';

export default defineConfig({
  integrations: [linkChecker()],
});

Options

linkChecker({
  // Pages to skip crawling entirely (string = prefix match, RegExp = tested against full path)
  excludeSourcePages: ['/landing/', /^\/preview\//],

  // Destinations to skip checking (string = prefix match, RegExp = tested against full path)
  excludeDestinations: ['/login', '/logout', /^\/external-tool\//],

  // Throw and fail the build on broken links (default: true)
  failOnBrokenLinks: true,

  // Log every checked href, not just broken ones (default: false)
  verbose: false,
})

Both excludeSourcePages and excludeDestinations accept an array of strings or RegExp objects:

• Strings match by prefix: e.g. '/login' excludes any path that starts with /login, such as /login, /login/callback, or /login?next=/docs. This is equivalent to the regex /^\/login/.
• RegExps match against the full path: use regex for patterns that don't anchor at the start, or for precise end-to-end matches.

excludeDestinations: [
  '/login',           // prefix: skips /login, /login/callback, /login?next=…
  '/external-tool/',  // prefix: skips /external-tool/ and everything beneath it
  /\/beta\//,         // regex: skips any path containing /beta/ (not anchored)
  /\.(pdf|zip)$/,     // regex: skips paths ending in .pdf or .zip
  /^\/exact-path$/,   // regex: skips only the exact path /exact-path
]

Output

[link-checker] 4231 HTML files
[link-checker] 8847 unique destinations
[link-checker] done in 2.1s
[link-checker] all links ok

On failure:

[link-checker] 2 broken links:
  /docs/get-started/missing-page
    /docs/overview
    /docs/quickstarts/react
    … and 12 more
  /docs/api/old-endpoint
    /docs/api/index

Notes

• Only checks href attributes, skips src (images, scripts).
• Strips anchor fragments (#section) before checking; does not verify whether the anchor actually exists on the target page.
• Resolves relative hrefs against their source file's location and normalized to root-relative paths before deduplication and matching.