Skip to content
Saimul Islam

static-preflight: a broken link checker for your static site build

A broken link checker and launch checklist for a static site build: SEO basics, links and assets, redirects, share cards, icons, JSON-LD and old-URL coverage.

Install
npm install -D static-preflight

Overview

static-preflight is a broken link checker that runs on the HTML your build wrote, before you deploy. It works with Next.js (output: export), Astro, Eleventy, Hugo, or anything else that writes HTML files, and fails the build when a launch would go wrong: a page without a title or description, a broken internal link or image, a share card pointing at a missing file, an old URL that no longer lands anywhere.

Link checkers such as linkinator look at links only, and html-validate looks at markup; neither knows about SEO basics, share cards, icons, JSON-LD or _redirects. This one does, in a single zero-dependency pass over a folder. It started as the pre-launch check run on every static site DeveloperLook ships.

Examples

Run it after the build
{
  "scripts": {
    "build": "next build",
    "postbuild": "static-preflight out"
  }
}
Or run it once without installing
npx static-preflight out
A launch check for a site that replaces an old one
static-preflight out --forbid-noindex --legacy-urls old-urls.txt --require-jsonld 'Product=/products/*'
Sample output
description (1)
  /contact/index.html: no meta description

alt (1)
  /menu/index.html: image without alt: /img/loaf.jpg

links (1)
  /contact/index.html: broken link /old-contact

anchors (1)
  /menu/index.html: anchor #pastries has no target

srcset (1)
  /products/sourdough/index.html: missing srcset image: /img/loaf@2x.jpg

stylesheets (1)
  /assets/site.css: missing file in url(): /img/bg.png

noindex (1)
  /contact/index.html: has a noindex robots tag

share-card (4)
  /contact/index.html: no og:title
  /contact/index.html: no og:description
  /contact/index.html: no og:image
  /contact/index.html: no twitter:card

jsonld (1)
  /products/sourdough/index.html: no Product JSON-LD

redirects (1)
  redirect /menu hides the page /menu

legacy-urls (2)
  old URL /product/rye-bread/ has no page and no redirect
  old URL /about-us/ has no page and no redirect

15 problems found. Checked 5 pages and 3 old URLs.
Use it from code
import { preflight } from 'static-preflight';

const { pages, problems } = preflight('out', {
  noindex: 'forbid',
  requireJsonLd: [{ type: 'Product', pattern: '/products/*' }],
});

for (const { check, page, message } of problems) console.log(`${check} ${page ?? ''} ${message}`);
if (problems.length) process.exitCode = 1;

Features

01Internal link checker
Internal links must resolve to a built page, a file or a _redirects source, including splats and placeholders. Relative links and base href are followed, and #fragment links must point at an id or anchor on the same page.
02Images, media and assets
img src, srcset candidates, video and audio files, linked stylesheets and the files their url() and @import point at, and script src files must exist in the folder.
03SEO basics on every page
A non-empty title and meta description, exactly one h1, and an alt attribute on every image.
04Share cards and icons
og:title, og:description, og:image and twitter:card are set, the image is a JPG or PNG that exists, and a favicon and an apple-touch-icon are linked and present.
05JSON-LD
Every JSON-LD block must parse, and pages that match a path pattern must carry the type you require, such as Product on /products/*.
06Redirects and old URLs
Redirect destinations must be built pages, no redirect may hide a page that exists, and every URL in a legacy list must still land on a page or a redirect.
07noindex guard
--forbid-noindex catches a noindex tag left on at launch (404 pages are exempt). --expect-noindex does the reverse for a site hidden before launch.

CLI usage

Usage
static-preflight [dir] [--expect-noindex | --forbid-noindex] [--legacy-urls file] [--require-jsonld Type=/pattern/*] [--skip check,check] [--json]
[dir]
The built folder. Default: out.
--forbid-noindex
No page may carry a noindex robots tag, except 404 pages.
--expect-noindex
Every page must carry a noindex robots tag.
--legacy-urls <file>
Old URLs that must still land somewhere: a JSON array, or a text file with one URL or path per line.
--require-jsonld <T=/p/*>
Pages matching the path pattern must carry JSON-LD of type T. Repeatable.
--skip <check,check>
Turn checks off. Repeatable.
--ignore <pattern>
Leave pages matching a URL path pattern out of every check.
--trailing-slash <rule>
forbid or require a trailing slash on links to pages.
--config <file>
Config file. Default: static-preflight.config.json in the working directory.
--json
Print the result as JSON instead of text.

Limits

  • It reads the HTML your build wrote, not what a browser renders. A link, heading or meta tag added by JavaScript at runtime is invisible to it.
  • External URLs are never fetched. It does not check that https://other.example is alive.
  • Only a Netlify or Cloudflare Pages style _redirects file is read. Rules in vercel.json, netlify.toml, _headers or server config are not.
  • A site served from a sub-path (a Next.js basePath, a GitHub Pages project site) is not supported.
  • Only #fragment links within the same page are checked, not /other-page#section.
  • The share image is judged by its extension and existence, not by its bytes or dimensions.
  • It does not validate markup, measure title length or judge content. Use an HTML validator for markup.

Frequently asked questions

How do I find broken links on a static site before I deploy?

Build the site, then run npx static-preflight out (or the folder your build writes). Every broken internal link, image, stylesheet and script is listed with the page it is on, and the command exits 1 so a CI build fails.

Does it check external links?

No. It is an internal link checker: external URLs are never fetched, so a build does not fail because another site was down. It checks that internal links, anchors and files resolve inside the built folder.

What belongs on a website launch checklist for a static site?

The checks cover the usual ones: a title, description and single h1 on every page, alt text, working links and assets, share card tags and image, icons, valid JSON-LD, redirects that land on real pages, old URLs that still resolve, and no noindex left on at launch.

Which static site generators does it work with?

Any that write HTML files to a folder: Next.js with output: export, Astro, Eleventy and Hugo are the ones the README names. It needs Node 20 or later and has no runtime dependencies.

  • Web QA

    siteprobe

    A fetch-only security headers checker and website scanner: about a hundred security, SEO and speed checks, with a score and a fix hint for each finding.

  • Web QA

    redirect-lint

    Find redirect chains, loops and clashes in a whole rule set, then flatten every chain to one hop before you ship.

  • Web QA

    viewport-qa

    Responsive design testing that measures the layout at every viewport width: overflow, clipping, inconsistent insets and radii, low-resolution images and layout shift.

See all 9 open-source packages

Author

Built by Saimul Islam

Saimul Islam is a Forward Deployed Engineer and Solutions Architect. Several of these packages run in production on DeveloperLook, the Bundlewise CRM and Sitessa.