vercel-seo-audit
Tech Stack
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.
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
Results
54+ GitHub stars, published on npm, used by Vercel community