@djangocfg/seo

SEO audit toolkit for Next.js App Router. Parallel execution, AI-ready split reports.

Part of DjangoCFG — modern Django framework for production-ready SaaS applications.

Two Modes

| Mode | Target | Use Case | |------|--------|----------| | Audit (HTTP) | Live site | Production SEO check, broken links, GSC data | | Content (files) | content/ dir | MDX link validation, sitemap generation |

Audit — crawls your deployed site via HTTP. Use for production audits.

Content — scans local MDX files in content/ directory. Use for Nextra/docs projects to validate links before deploy and generate sitemap.ts.

Quick Start

pnpm add @djangocfg/seo

# Full SEO audit
djangocfg-seo audit

# Scan app/ routes and compare with sitemap
djangocfg-seo routes --check

# Check broken links
djangocfg-seo links

Commands

| Command | Description | |---------|-------------| | audit | Full audit (robots + sitemap + crawl + links + routes + GSC) | | routes | Scan app/ directory, compare with sitemap | | crawl | Crawl site, analyze meta/titles/H1 | | links | Check for broken links | | robots | Analyze robots.txt | | sitemap | Validate sitemap.xml | | inspect | GSC URL inspection | | content check | Check MDX links in content/ | | content fix | Fix absolute → relative links | | content sitemap | Generate sitemap.ts from content/ |

Options

--env, -e          prod (default) or dev
--site, -s         Site URL (overrides env)
--output, -o       Output directory (default: ./seo-reports)
--format, -f       split (default), json, markdown, ai-summary, all
--max-pages        Max pages to crawl (default: 100)
--service-account  Google service account JSON path
--app-dir          Path to app/ directory
--check            Compare routes with sitemap
--verify           Verify routes are accessible

Routes Command

Scans Next.js App Router app/ directory:

djangocfg-seo routes           # List all routes
djangocfg-seo routes --check   # Compare with sitemap
djangocfg-seo routes --verify  # Verify routes return 200

Output:

Routes found: 16
├── Static: 11
├── Dynamic: 1
└── API: 4

Sitemap comparison:
├── Matching: 8
├── Missing from sitemap: 3
└── Extra in sitemap: 50

Handles: route groups (group), dynamic [slug], catch-all [...slug], parallel @folder, private _folder.

Reports

Default split format - AI-optimized files under 1000 lines:

@reports/seo/
├── CLAUDE.md              # AI context file
├── seo-*-index.md         # Summary + links to categories
├── seo-*-technical.md     # Broken links, sitemap, robots.txt
├── seo-*-content.md       # H1, meta, titles
├── seo-*-performance.md   # Load time, TTFB
└── seo-ai-summary-*.md    # Quick overview

Google Search Console

Auto-detects gsc-key.json in project root:

1. Create service account: console.cloud.google.com
2. Download JSON key as gsc-key.json
3. Enable API: searchconsole API
4. Add service account email to GSC with Full access
5. Run audit - GSC data included automatically

Programmatic Usage

import { SiteCrawler, analyzeCrawlResults } from '@djangocfg/seo/crawler';
import { checkLinks, linkResultsToSeoIssues } from '@djangocfg/seo/link-checker';
import { scanRoutes, compareWithSitemap } from '@djangocfg/seo/routes';
import { generateAndSaveReports } from '@djangocfg/seo/reports';

// Crawl
const crawler = new SiteCrawler('https://example.com', { maxPages: 100 });
const results = await crawler.crawl();
const crawlIssues = analyzeCrawlResults(results);

// Routes
const routes = scanRoutes({ appDir: './app' });
console.log(routes.staticRoutes, routes.dynamicRoutes);

// Links
const linkResult = await checkLinks({ url: 'https://example.com' });
const linkIssues = linkResultsToSeoIssues(linkResult);

// Reports
await generateAndSaveReports('https://example.com', {
  issues: [...crawlIssues, ...linkIssues],
}, {
  outputDir: './reports',
  formats: ['split'],
});

Exports

// Main
import { SiteCrawler, checkLinks, GoogleConsoleClient } from '@djangocfg/seo';

// Submodules
import { SiteCrawler, analyzeCrawlResults } from '@djangocfg/seo/crawler';
import { checkLinks, linkResultsToSeoIssues } from '@djangocfg/seo/link-checker';
import { scanRoutes, compareWithSitemap, verifyRoutes } from '@djangocfg/seo/routes';
import { GoogleConsoleClient } from '@djangocfg/seo/google-console';
import { generateAndSaveReports } from '@djangocfg/seo/reports';
import type { SeoIssue, SeoReport, CrawlResult } from '@djangocfg/seo/types';

Issue Types

| Severity | Description | |----------|-------------| | critical | Blocks indexing | | error | SEO problems | | warning | Recommendations | | info | Best practices |

| Category | Examples | |----------|----------| | technical | Broken links, sitemap, robots.txt | | content | Missing H1, meta description | | indexing | Not indexed, crawl errors | | performance | Slow load time, high TTFB |

Architecture

djangocfg-seo audit
    │
    ├─ robots.txt → get sitemap URLs
    │
    ├─ [PARALLEL] ─┬─ Sitemap
    │              ├─ Crawl (+ TTFB metrics)
    │              └─ Links
    │
    ├─ Routes (compare with sitemap)
    │
    └─ GSC (sc-domain:xxx)
           │
           └─ @reports/seo/

License

MIT