static-link-sentinel weekly downloads statistics

static-link-sentinel

Run it on your built static site (dist/, build/, out/, public/, _site/) before you deploy. It finds broken internal links, missing assets, missing #anchors and paths whose letter case only works on macOS, then fails CI. With --external it also checks outbound links for 404s and redirect chains, showing every hop. You don't need a server: it maps URLs to files the way Netlify, Vercel, GitHub Pages and Cloudflare Pages do (clean URLs, index.html, trailingSlash, basePath, _redirects, vercel.json). Each problem comes with a fix line, such as did you mean /blog/post-1/? Zero dependencies, Node ≥ 18. Output can be JSON, SARIF or Markdown, and it ships with Vite and webpack plugins and a GitHub Action.

Quick start

npm run build
npx static-link-sentinel            # auto-detects dist/ build/ out/ public/ _site/
npx static-link-sentinel dist --external --site-url https://example.com

npm i -D static-link-sentinel
# package.json: "postbuild": "static-link-sentinel dist"

Usage

static-link-sentinel [dir] [options]      dir defaults to dist/build/out/public/_site

  -b, --base-path <path>      Site is served under a sub-path (e.g. /docs)
  -s, --site-url <url>        Production URL: absolute links to it are checked as internal
      --trailing-slash <m>    always | never | ignore (default: ignore, or vercel.json)
      --clean-urls            Host serves /about for about.html (default: vercel.json cleanUrls)
      --orphans               Report pages no other page links to
  -e, --external              Also check external links (HEAD, GET fallback)
      --concurrency <n>       Parallel external requests (default 8)
      --per-host <n>          Parallel requests per host (default 2)
      --host-delay <ms>       Minimum gap between requests to one host (default 150)
      --timeout <ms>          Per-request timeout (default 10000)
      --retries <n>           Retries on timeout/5xx/429 (default 2)
      --user-agent <ua>       User-Agent for external requests
      --skip <pattern>        Don't fetch matching external URLs (repeatable; adds to defaults)
      --cache-file <file>     External result cache (default .link-cache.json)
      --cache-ttl <hours>     Cache lifetime (default 24)
      --no-cache              Don't read or write the cache
      --sources [pattern...]  Also scan markdown/mdx under the project (default **/*.md, **/*.mdx)
  -i, --ignore <pattern>      Ignore matching URLs (glob, substring or re:regex; repeatable)
  -c, --config <file>         JSON config
      --fail-on <level>       error | warn | none (default error)
      --json                  JSON report on stdout
      --sarif [file]          SARIF 2.1.0 to stdout or file (--sarif=out.sarif)
      --markdown [file]       Markdown summary (PR comments, job summary) to stdout or file
  -q, --quiet                 Hide info-level findings in the pretty output

Exit codes: 0 passed, 1 findings at or above --fail-on, 2 usage error (bad flag, missing directory, unreadable config). Colours turn off when NO_COLOR is set or stdout is not a TTY (FORCE_COLOR=1 forces them).

Sample output

$ npx static-link-sentinel dist --site-url https://mysite.com --orphans
static-link-sentinel: dist/ 5 page(s), 1 stylesheet(s), 13 file(s), 41 internal reference(s), 2 external link(s) not checked (use --external)

assets/style.css
  ✖ error Missing asset [missing-asset]  line 2
          ../img/bg.png resolves to no file in the build (would serve 404.html)
          fix: Check the build output and asset paths (publicPath/base).

index.html
  ✖ error Mixed content [mixed-content]  line 14
          <script src="http://cdn.example.com/lib.js"> loads over http:// and will be blocked on https
          fix: Use https://cdn.example.com/lib.js
  ✖ error Broken internal link [broken-link]  line 21
          <a href="/blog/post-l/"> resolves to no file in the build (would serve 404.html)
          fix: did you mean /blog/post-1/?
  ✖ error Path case mismatch [case-mismatch]  line 22
          <a href="/Blog/Post-1/"> only matches blog/post-1/index.html with different case (fails on Linux/CDN hosts)
          fix: Use /blog/post-1/ or rename the file
  ⚠ warn  Missing #fragment anchor [missing-fragment]  line 24
          <a href="/about#tem">: no id="tem" in about.html
          fix: did you mean #team?
  ℹ info  Absolute link to own domain [absolute-internal]  line 31
          <a href="https://mysite.com/about"> hard-codes the production domain
          fix: Use a relative link: /about
  ✖ error Path case mismatch [case-mismatch]  line 34
          <img src="/img/Logo.png"> only matches img/logo.png with different case (fails on Linux/CDN hosts)
          fix: Use /img/logo.png or rename the file

sitemap.xml
  ✖ error sitemap.xml URL not in build [sitemap-url]  line 5
          <loc>https://mysite.com/gone/</loc> has no matching page in the build
          fix: Regenerate the sitemap or remove the entry

5 page(s) checked: 17 error(s), 5 warning(s), 2 info

With --external:…