@capgo/seo-checker

Static SEO checker for analyzing built HTML files in dist folders. Performs comprehensive SEO analysis with 1000+ rules covering metadata, content quality, accessibility, structured data, and more.

Inspired by Ahrefs SEO Audit and Lighthouse SEO audits, but focused on static sites built with frameworks like Astro, Next.js, SvelteKit, etc.

Installation

npm install @capgo/seo-checker
# or
bun add @capgo/seo-checker

CLI Usage

# Run with default settings (scans ./dist)
npx @capgo/seo-checker

# Specify dist path
npx @capgo/seo-checker --dist ./build

# Output as JSON
npx @capgo/seo-checker --output json

# Generate a sample config file
npx @capgo/seo-checker --generate-config

CLI Options

| Option | Description | Default | | ------------------- | ------------------------------------------- | ------------------------- | | --dist <path> | Path to dist folder | ./dist | | --config <path> | Path to config file | seo-checker.config.json | | --output <format> | Output format: console, json, sarif, github | console | | --report <path> | Path to write report file | - | | --fail-on <level> | Fail on: error, warning, notice | error | | --max-issues <n> | Maximum issues before stopping | 0 (unlimited) | | --generate-config | Generate a sample config file | - |

Configuration

Create a seo-checker.config.json file:

{
  "distPath": "./dist",
  "baseUrl": "https://example.com",
  "languages": ["en", "es", "fr"],
  "defaultLanguage": "en",
  "rules": {
    "disabled": ["SEO00186", "SEO00189"],
    "severityOverrides": {
      "SEO00135": "notice"
    }
  },
  "exclusions": [
    {
      "ruleId": "SEO00147",
      "filePath": "404.html",
      "reason": "404 page intentionally has broken link examples"
    }
  ],
  "failOn": ["error"],
  "maxIssues": 0,
  "outputFormat": "console"
}

Programmatic Usage

import {
  checkDuplicates,
  printReport,
  runPageChecks,
  scanDistFolder
} from '@capgo/seo-checker'

const config = {
  distPath: './dist',
  baseUrl: 'https://example.com',
  languages: ['en'],
  defaultLanguage: 'en',
}

// Scan the dist folder
const siteData = await scanDistFolder(config)

// Run checks on each page
const issues = []
for (const page of siteData.pages.values()) {
  issues.push(...runPageChecks(page, config, siteData))
}

// Check for duplicates
issues.push(...checkDuplicates(siteData, config))

console.log(`Found ${issues.length} SEO issues`)

Rules Categories

The checker includes 1000+ rules across these categories:

• Metadata: Title, description, canonical, charset, lang
• Content Length: Title/description/heading length limits
• Content Format: Whitespace, encoding, caps, punctuation
• Headings: H1 presence, hierarchy, duplicates
• Indexability: Robots directives, canonical issues
• Links: Broken links, anchor text, nofollow usage
• Images: Alt text, file size, broken references
• Social Tags: OpenGraph, Twitter cards
• International SEO: Hreflang, lang attributes
• Structured Data: JSON-LD validation
• Accessibility: Landmarks, skip links, ARIA
• Robots.txt & Sitemap: Validation and consistency

Output Formats

Console (default)

Colored terminal output grouped by category with severity indicators.

JSON

Machine-readable JSON with all issues and statistics.

SARIF

Static Analysis Results Interchange Format for CI/CD integration.

GitHub

GitHub Actions workflow commands format. Issues appear as annotations in the PR/commit view.

# Use in GitHub Actions
npx @capgo/seo-checker --output github

Example workflow:

- name: SEO Check
  run: npx @capgo/seo-checker --output github --fail-on error,warning

License

MIT