Static SEO checker for analyzing built HTML files in dist folders
npm install @capgo/seo-checkerStatic 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.
``bash`
npm install @capgo/seo-checkeror
bun add @capgo/seo-checker
`bashRun with default settings (scans ./dist)
npx @capgo/seo-checker
$3
| Option | Description | Default |
| ------------------- | ------------------------------------------- | ------------------------- |
|
--dist | Path to dist folder | ./dist |
| --config | Path to config file | seo-checker.config.json |
| --output | Output format: console, json, sarif, github | console |
| --report | Path to write report file | - |
| --fail-on | Fail on: error, warning, notice | error |
| --max-issues | Maximum issues before stopping | 0 (unlimited) |
| --generate-config | Generate a sample config file | - |Configuration
Create a
seo-checker.config.json file:`json
{
"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
`typescript
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
$3
Colored terminal output grouped by category with severity indicators.
$3
Machine-readable JSON with all issues and statistics.
$3
Static Analysis Results Interchange Format for CI/CD integration.
$3
GitHub Actions workflow commands format. Issues appear as annotations in the PR/commit view.
`bash
Use in GitHub Actions
npx @capgo/seo-checker --output github
`Example workflow:
`yaml
- name: SEO Check
run: npx @capgo/seo-checker --output github --fail-on error,warning
``MIT