sitemap-healthcheck

Detect silent sitemap corruption in CI. Validates a sitemap index, walks every child sitemap, and asserts URL counts, freshness, and HTTP status against a config.

npm install -D sitemap-healthcheck

Why

A sitemap regression rarely throws an error — your CMS just emits an empty <urlset> and search engines silently de-index pages. This package gives you a single command that fails CI when:

• the sitemap index 404s or returns fewer sitemaps than expected
• any child sitemap is empty, missing, or below a per-pattern minimum
• a sitemap's Last-Modified is older than your max-age threshold

Output modes: pretty TTY, JSON, and GitHub Actions annotations.

CLI

npx sitemap-healthcheck --url https://example.com/sitemap.xml
npx sitemap-healthcheck --url https://example.com/sitemap.xml --config healthcheck.json --github

healthcheck.json

{
  "minSitemapsInIndex": 50,
  "defaultMinUrls": 1,
  "defaultMaxAgeDays": 7,
  "rules": [
    { "match": "sitemap-breeds-(de|en)\\.xml", "minUrls": 1200 },
    { "match": "sitemap-shelter-dogs-de\\.xml", "minUrls": 6000 },
    { "match": "sitemap-videos-.*\\.xml", "optional": true }
  ]
}

Match patterns are regex (string or RegExp). First match wins.

Exit codes

| Code | Meaning | | --- | --- | | 0 | all healthy | | 1 | warnings only (low URL counts, stale, optional missing) | | 2 | critical (index unreachable, empty sitemap, required missing) |

Library

import { runHealthcheck, printReport } from "sitemap-healthcheck";

const report = await runHealthcheck({
  indexUrl: "https://example.com/sitemap.xml",
  defaultMinUrls: 1,
  rules: [{ match: /breeds/, minUrls: 1000 }],
});

printReport(report);
process.exit(report.exitCode);

The report shape:

{
  indexUrl: string;
  index: { status, sitemapCount, reason?, httpStatus? };
  sitemaps: Array<{ name, url, status, urlCount, expectedMin?, ageDays?, lastModified?, reason?, httpStatus? }>;
  totals: { healthy, warning, critical, totalUrls };
  exitCode: 0 | 1 | 2;
}

GitHub Actions

- name: Sitemap healthcheck
  run: npx sitemap-healthcheck --url ${{ env.SITE_URL }}/sitemap.xml --config healthcheck.json --github

--github emits ::warning:: and ::error:: annotations attached to the run.

License

MIT