@djangocfg/seo

@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:

• Create service account: console.cloud.google.com
• Download JSON key as gsc-key.json
• Enable API: searchconsole API
• Add service account email to GSC with Full access
• 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