@seobeast/seo-audit

v0.2.1

Published

16 days ago

Programmatic SEO audit library — 140+ rules across 20 categories. TypeScript-first, ESM, no browser required.

0High
0Medium
0Low

tanuj-rgb

seo audit seo-audit technical-seo aeo core-web-vitals typescript

seobeast-audit

Full-site SEO audit with 140+ rules across 20 categories. Ships as both a Claude Code skill and a TypeScript npm library with proper ESM exports.

Claude Code Skill

claude install https://github.com/seobeast-co/seobeast-audit

Then in any Claude Code session:

/seobeast-audit https://yoursite.com

Spawns 6 specialist subagents in parallel (technical, content, performance, security, structured data, AEO) and returns a unified report with a composite 0–100 score.

Sample output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  seobeast-audit  ·  https://example.com
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Score: 58/100  [████████████░░░░░░░░]  Grade: D

  Technical SEO    [████████░░]  76/100   8 issues
  Content          [███████░░░]  68/100   5 issues
  Performance      [█████░░░░░]  52/100   11 issues
  Security         [████████░░]  80/100   3 issues
  Structured Data  [███░░░░░░░]  30/100   4 issues
  AEO              [██░░░░░░░░]  24/100   6 issues

── Critical ─────────────────────────────────────────
  ✗  GPTBot blocked in robots.txt  (AEO)
  ✗  No JSON-LD structured data  (Structured Data)

── High Priority ────────────────────────────────────
  ⚠  4 render-blocking scripts in <head>  (Performance)
  ⚠  Meta description missing  (Technical)

── Medium Priority ──────────────────────────────────
  ⚠  No llms.txt found  (AEO)
  ⚠  HSTS header not set  (Security)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  seobeast-audit · seobeast.co
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

npm Library

npm install @seobeast/seo-audit

import { createAuditor } from '@seobeast/seo-audit';

const auditor = createAuditor();
const result = await auditor.audit('https://example.com');

console.log(`Score: ${result.overallScore}/100  Grade: ${result.grade}`);

for (const category of result.categoryResults) {
  console.log(`  ${category.categoryId}: ${category.score}/100  (${category.failCount} failures)`);
}

With options:

const auditor = createAuditor({
  categories: ['core', 'security', 'aeo'],   // run specific categories only
  timeout: 10_000,                            // ms per request
  onCategoryComplete: (id, name, result) => {
    console.log(`${name}: ${result.score}/100`);
  },
});

Crawl mode (multi-page):

const result = await auditor.auditWithCrawl('https://example.com', {
  maxPages: 20,
  concurrency: 4,
});
console.log(`Crawled ${result.crawledPages} pages — score: ${result.overallScore}/100`);

Custom rules:

import { createAuditor, defineRule, registerRule, pass, fail } from '@seobeast/seo-audit';

registerRule(defineRule({
  id: 'custom-my-rule',
  name: 'My Custom Check',
  description: 'Checks for my specific requirement',
  category: 'core',
  weight: 5,
  run: ({ $ }) => {
    const el = $('#my-required-element');
    if (!el.length) return fail('custom-my-rule', '#my-required-element not found');
    return pass('custom-my-rule', '#my-required-element present');
  },
}));

const auditor = createAuditor();
const result = await auditor.audit('https://example.com');

Categories and Weights

| Category | Weight | What it checks | |---|---|---| | Core SEO | 14% | Title, description, H1, canonical, viewport, favicon, robots meta | | Performance | 12% | Render-blocking, lazy loading, image dimensions, resource hints, compression | | Content | 10% | Word count, headings, thin content, freshness, duplicate meta | | Technical SEO | 7% | Doctype, lang, charset, heading hierarchy, canonical-URL match | | Crawlability | 7% | robots.txt, sitemap, noindex, crawl directives | | Links | 6% | Internal links, anchor text, nofollow usage | | Security | 6% | HTTPS, HSTS, CSP, X-Frame-Options, mixed content | | Structured Data | 6% | JSON-LD, Organization, Article, BreadcrumbList, Product | | AEO Readiness | 5% | GPTBot/ClaudeBot/PerplexityBot access, llms.txt, passage citability | | Images | 5% | Alt text, dimensions, lazy load, modern formats, srcset | | E-E-A-T | 5% | Author, dates, about/contact pages, external citations | | Social | 3% | OG tags, Twitter Card | | Mobile | 3% | Viewport, font size, tap targets | | Accessibility | 3% | Heading order, form labels, landmark regions | | URL Structure | 2% | Length, hyphens vs underscores, descriptive slugs | | Redirects | 2% | Chain length, HTTPS enforcement, www consistency | | JavaScript | 1% | Render-blocking JS, CSR detection, external script count | | Internationalization | 1% | lang attribute, hreflang, charset | | HTML Validation | 1% | Doctype, charset placement, duplicate declarations | | Legal | 1% | Privacy policy, cookie consent, terms |

TypeScript API

import type {
  AuditResult,
  CategoryResult,
  RuleResult,
  AuditContext,
  AuditRule,
  AuditorOptions,
} from '@seobeast/seo-audit';

All types are exported. Full type definitions in src/types.ts.

Requirements

Node.js 18+
No browser required (pure HTTP + HTML parsing via cheerio)
No API keys required

License

MIT

For history tracking, content generation, and CMS publishing — seobeast.co

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme