npm package: @seobeast/seo-audit
Description: Programmatic SEO audit library — 140+ rules across 20 categories. TypeScript-first, ESM, no browser required.
Latest version: 0.2.1

# 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

```bash
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

```bash
npm install @seobeast/seo-audit
```

```typescript
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:**

```typescript
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):

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

**Custom rules:**

```typescript
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

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

All types are exported. Full type definitions in [src/types.ts](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](https://seobeast.co)