Embedding Claude-SEO Skills into Next.js 16: An Open-Source Technical Audit Blueprint

#nextjs #react #typescript #seo

The popular AgriciDaniel/claude-seo project demonstrated that modern AI models, when equipped with specialized domain prompts and systematic heuristics, can execute SEO audits comparable to senior technical consultants.

However, running these prompts manually through a chat window has major friction:

You have to manually scrape your HTML, clean it, and paste it into the chat prompt.
You do not get live PageSpeed Core Web Vitals telemetry.
You cannot automate it into your CI/CD deployment pipeline or schedule recurring scans.
The model cannot visually inspect your rendered viewport.

In ⚡ PLYXO (CRO • SEO • AIO • AEO • GEO), we took this concept to the next level by natively porting the entire Claude-SEO Skills suite directly into a production full-stack Next.js 16 + React 19 + TypeScript application.

Here is the architectural blueprint of how it works.

1. The Embedded Claude-SEO Skills Matrix

We codified the 6 core pillars of Claude-SEO into programmatic diagnostic modules:

┌────────────────────────────────────────────────────────────────────────┐
│               PLYXO EMBEDDED CLAUDE-SEO SKILLS PIPELINE                │
├──────────────────────────┬──────────────────────┬──────────────────────┤
│ 1. ⚙️ Technical SEO      │ 2. 📝 Content E-E-A-T│ 3. 📐 Schema/JSON-LD │
│ • Sitemaps & robots.txt  │ • Lexical Diversity  │ • Schema.org parsing │
│ • Canonical directives   │ • Flesch-Kincaid ease│ • FAQ/Article types  │
│ • Hydration & SSR state  │ • Thin-content check │ • OpenGraph/Twitter  │
├──────────────────────────┼──────────────────────┼──────────────────────┤
│ 4. 🤖 AI / AEO / GEO     │ 5. 🔑 Semantic Gap   │ 6. 🔗 Link Integrity │
│ • Perplexity Citations   │ • Search Intent class│ • Dead 404 crawler   │
│ • Knowledge Graph tokens │ • Keyword cannibal   │ • Internal pagerank  │
│ • Direct-Answer density  │ • Competitor gaps    │ • Redirect loop trap │
└──────────────────────────┴──────────────────────┴──────────────────────┘

2. Next.js 16 Server-Side Diagnostic Architecture

In Next.js 16 with Turbopack, we execute deep audits via asynchronous server actions and Node.js worker threads to keep UI responses sub-second:

Browser Client (React 19)
      │
      │ 1. Trigger Audit (URL: example.com)
      ▼
Next.js 16 Server Action (src/actions/audit.ts)
      │
      ├──> Worker A: Parallel SSR Scraper (SSRF-protected)
      │
      ├──> Worker B: Google PageSpeed Insights API (LCP, CLS, INP)
      │
      └──> Worker C: Structured Schema & JSON-LD Validator
               │
               ▼ Aggregate Telemetry Payload
               │
      LLM Reasoning Pipeline (Google Gemini 2.0 / Claude API)
               │
               ▼ Structured JSON Output (Zod Schema Validation)
               │
Persisted to PostgreSQL via Drizzle ORM
      │
      ▼
Real-Time Telemetry Streamed to React 19 Client via React Server Components

3. Real Code: The Schema & JSON-LD Diagnostic Parser

Here is a look at the TypeScript parsing engine that extracts and validates Schema.org entities from raw HTML before passing them to the AI reasoning model:

import * as cheerio from 'cheerio';
import { z } from 'zod';

export interface SchemaValidationResult {
  hasJsonLd: boolean;
  schemasFound: string[];
  syntaxErrors: string[];
  missingRequiredFields: Record<string, string[]>;
}

export function auditSchemaMarkup(htmlContent: string): SchemaValidationResult {
  const $ = cheerio.load(htmlContent);
  const jsonLdScripts = $('script[type="application/ld+json"]');

  const result: SchemaValidationResult = {
    hasJsonLd: jsonLdScripts.length > 0,
    schemasFound: [],
    syntaxErrors: [],
    missingRequiredFields: {}
  };

  jsonLdScripts.each((_, el) => {
    const rawContent = $(el).html()?.trim();
    if (!rawContent) return;

    try {
      const parsed = JSON.parse(rawContent);
      const schemaType = parsed['@type'] || 'Unknown';
      result.schemasFound.push(schemaType);

      // Validate critical fields for Article & Product types
      if (schemaType === 'Article' || schemaType === 'BlogPosting') {
        const required = ['headline', 'datePublished', 'author', 'publisher'];
        const missing = required.filter(field => !parsed[field]);
        if (missing.length > 0) {
          result.missingRequiredFields[schemaType] = missing;
        }
      }
    } catch (err: any) {
      result.syntaxErrors.push(`Malformed JSON-LD syntax: ${err.message}`);
    }
  });

  return result;
}

4. Structured Output with Zod Schema Validation

When querying LLMs for technical SEO diagnosis, hallucinated unstructured responses ruin reliability. We enforce strict JSON schema contracts using Zod:

import { z } from 'zod';

export const TechnicalSeoAuditSchema = z.object({
  score: z.number().min(0).max(100),
  criticalIssues: z.array(
    z.object({
      id: z.string(),
      title: z.string(),
      severity: z.enum(['CRITICAL', 'WARNING', 'INFO']),
      description: z.string(),
      codeFixRecommendation: z.string().optional(),
    })
  ),
  coreWebVitalsImpact: z.object({
    lcpImpactMs: z.number(),
    clsImpactDelta: z.number(),
    inpDelayMs: z.number()
  }),
  aeoReadinessSummary: z.string()
});

Because the output is strongly typed, the Next.js frontend renders instant interactive diagnostic badges, copyable code diffs, and exportable PDF audit reports without any JSON parsing errors.

5. Check Out the Open-Source Repo

Everything mentioned here—from the schema parsers to the multi-tier crawlers and Next.js 16 UI—is completely open-source under the FSL-1.1-MIT license.

👉 View the full repository: pixelfogg/Plyxo-CRO-SEO-AIO-AEO-GEO

Coming up in Day 4: **The Mathematics of Visual Friction* — how we calculate real projected dollar revenue loss from UI bounding-box inspect telemetry.*

DEV Community