@site-os/check

Fork notice. This package is a hard fork of Cap-go/seo-checker by Capgo (MIT, with permission), used as the foundation for siteOS. Upstream remains the canonical static SEO checker; this fork extends it with remote URL crawling, a local server spawn mode, and dashboard integration. See LICENSE for dual copyright.

OSS SEO checker for static sites and CI pipelines. Performs comprehensive SEO analysis with 1000+ rules covering metadata, content quality, accessibility, structured data, and more. The static --dist mode inherited from upstream is preserved; remote URL crawling and --start modes are being added on top.

Inspired by Ahrefs SEO Audit and Lighthouse SEO audits.

Installation

npm install @site-os/check
# or
bun add @site-os/check

CLI Usage

# Run with default settings (scans ./dist)
npx @site-os/check

# Specify dist path
npx @site-os/check --dist ./build

# Output as JSON
npx @site-os/check --output json

# Generate a sample config file
npx @site-os/check --generate-config

CLI Options

| Option | Description | Default | | ------------------- | ------------------------------------------- | -------------------------- | | --dist <path> | Path to dist folder | ./dist | | --config <path> | Path to config file | siteos-check.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 siteos-check.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 '@site-os/check'

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 @site-os/check --output github

Example workflow:

- name: SEO Check
  run: npx @site-os/check --output github --fail-on error,warning

License

MIT — see LICENSE for dual copyright (Capgo for original work, Vincent Ventalon for modifications).