back to projects

vercel-seo-audit

If you're using Vercel and Google hates your site, this is for you. CLI tool that audits robots.txt, sitemaps, meta tags, structured data, Open Graph, security headers, and more. Published on npm with 54+ GitHub stars.

2025oss#web

vercel-seo-audit

Overview

vercel-seo-audit is an open-source CLI tool I built specifically for developers deploying on Vercel who need a quick, comprehensive SEO health check. One command — npx vercel-seo-audit — finishes in 2–3 seconds and runs 11 audit modules in parallel using a two-phase execution model. Phase 1 handles robots.txt and redirect checks to produce prerequisite data, then Phase 2 runs everything else in parallel: sitemap validation, metadata analysis, favicon detection, Next.js-specific gotchas (trailing slash 308 traps, middleware rewrites), structured data (JSON-LD), Open Graph and Twitter Card tags, hreflang/i18n validation, image SEO, and security headers. With --crawl, it fetches every URL from your sitemap and audits each page individually. It also supports --diff to compare against previous audits, --strict mode for CI pipelines (any warning fails the build), and .seoauditrc.json config files for team-wide settings. The tool has zero heavy dependencies — just chalk, cheerio, commander, and fast-xml-parser. No headless browser, no Puppeteer. Available as a GitHub Action for seamless CI integration.

Stack

TypeScript · Node.js · CLI · SEO · Open Source

Challenges

  • Parsing and validating diverse HTML structures across different frameworks and SSR/SSG outputs
  • Catching invisible SEO killers like X-Robots-Tag headers set by middleware or CDN that don't show any symptoms in the browser
  • Designing a two-phase execution model where prerequisite data (robots.txt, redirects) feeds into all downstream audit modules
  • Supporting full sitemap crawl mode with configurable concurrency while keeping the tool resilient to partial failures
  • Ensuring the tool works reliably across Node.js 18/20/22 and integrates cleanly into CI/CD pipelines

Solutions

  • Built a modular audit architecture with 11 independent plugins that run in parallel, each receiving a shared AuditContext with data from prerequisite checks
  • Used Promise.allSettled() in every module so a timeout or failure in one check never blocks the rest — you always get results
  • Implemented a GitHub Action (JosephDoUrden/vercel-seo-audit@v1) with --strict and --diff flags for regression detection in CI
  • Added .seoauditrc.json config file support so teams can standardize audit settings while individual devs override via CLI flags
  • Comprehensive test suite with CI across Node 18/20/22, published with strict semver versioning on npm

Outcome

54+ GitHub stars, published on npm, used by Vercel community