Can OpenSEO Be Used for Technical SEO Audits? Complete Implementation Guide

Yes, OpenSEO can be used for comprehensive technical SEO audits through its multi-phase site-audit pipeline that crawls websites, validates robots.txt and sitemaps, runs Lighthouse performance checks, and applies rule-based issue detection.

The every-app/open-seo repository provides a production-ready technical SEO audit system built on Cloudflare Workers. It combines a custom crawler with automated issue detection to deliver commercial-grade audit capabilities comparable to paid SEO tools, accessible via both a web interface and programmable server functions.

Technical SEO Audit Architecture

OpenSEO implements a complete site-audit pipeline through five integrated layers. According to the source code, this architecture supports full technical SEO audits by combining discovery, crawling, performance testing, and issue analysis.

The Five-Layer Architecture

Layer	Component	Key Responsibilities
API Layer	src/serverFunctions/audit.ts	Exposes startAudit, getAuditStatus, getAuditResults, and deleteAudit functions with Zod schema validation
Service Layer	src/server/features/audit/services/AuditService.ts	Orchestrates audit creation, capacity checks, workflow launch, and result aggregation
Workflow Engine	src/server/workflows/siteAuditWorkflowPhases.ts	Executes the five-phase audit: Discovery → Crawl → Lighthouse → Issue Processing → Finalisation
Issue Engine	src/server/lib/audit/issues/*	Runs per-page and cross-page rule checks for technical SEO signals
Front-End	web/src/routes/_marketing/features/site-audit.tsx	Renders the Site Audit UI wizard at /features/site-audit

The Audit Workflow Phases

As implemented in src/server/workflows/siteAuditWorkflowPhases.ts, the technical SEO audit proceeds through distinct phases:

1. Discovery – Parses robots.txt and sitemaps to identify crawlable URLs
2. Crawl – Performs BFS crawling of same-origin URLs with configurable page caps
3. Lighthouse – Optional mobile/desktop performance and accessibility checks
4. Finalisation – Executes multipage checks, inserts detected issues, and emits completion events

Starting a Technical SEO Audit Programmatically

To initiate a technical SEO audit, invoke the startAudit server function defined in src/serverFunctions/audit.ts. This function validates input against Zod schemas in src/types/schemas/audit.ts before delegating to AuditService.startAudit.

import { startAudit } from '@/serverFunctions/audit';

async function runTechnicalAudit() {
  const { auditId } = await startAudit({
    projectId: 'proj_123',
    startUrl: 'https://example.com',
    maxPages: 100,               // Optional: defaults to plan limit
    lighthouseStrategy: 'auto',  // 'auto' | 'none'
  });

  console.log('Technical SEO audit started with ID:', auditId);
}

The AuditService.startAudit method (lines 41-66 in src/server/features/audit/services/AuditService.ts) generates a UUID audit ID, stores the audit row, and launches the Cloudflare Workers workflow via env.SITE_AUDIT_WORKFLOW.

Monitoring Technical SEO Audit Progress

Poll the audit status using getAuditStatus, which calls AuditService.getStatus and includes self-healing logic for stalled workflows.

import { getAuditStatus } from '@/serverFunctions/audit';

async function pollAuditProgress(auditId: string) {
  const status = await getAuditStatus({ 
    projectId: 'proj_123', 
    auditId 
  });
  
  console.log('Current phase:', status.currentPhase);
  console.log('Pages crawled:', status.pagesCrawled);
  console.log('Lighthouse progress:', status.lighthouseProgress);
}

Retrieving Technical SEO Audit Results

Once complete, fetch the structured audit report containing pages, Lighthouse scores, and detected technical issues.

import { getAuditResults } from '@/serverFunctions/audit';

async function fetchTechnicalAuditReport(auditId: string) {
  const report = await getAuditResults({ 
    projectId: 'proj_123', 
    auditId 
  });
  
  console.log('Pages audited:', report.pages.length);
  console.log('Performance scores:', report.lighthouseResults);
  console.log('Technical issues:', report.issues.length);
}

The getAuditResults function aggregates data via AuditRepository.getAuditResultsForProject as implemented in AuditService.getResults (lines 62-74).

Technical SEO Checks and Issue Detection

The issue engine in src/server/lib/audit/issues/* performs comprehensive technical SEO validation:

• Missing or duplicate <title> tags
• Broken internal links and redirect loops
• Duplicate meta descriptions and canonical conflicts
• Indexability issues (noindex directives, robots.txt blocking)
• Response time analysis and server error detection

These checks run during the Finalisation phase on normalized crawl data stored in Cloudflare D1, enabling cross-page analysis for duplicate content detection.

Managing Audit Lifecycle

Delete completed or stalled audits using the deleteAudit function, which invokes AuditService.remove to terminate running workflows and clean up database rows.

import { deleteAudit } from '@/serverFunctions/audit';

await deleteAudit({ projectId: 'proj_123', auditId: 'audit_456' });

Summary

• OpenSEO provides a complete technical SEO audit pipeline through Cloudflare Workers, supporting discovery, crawling, Lighthouse testing, and issue detection.
• The workflow is implemented in src/server/workflows/siteAuditWorkflowPhases.ts with five distinct phases from discovery to finalisation.
• Server functions (startAudit, getAuditStatus, getAuditResults) in src/serverFunctions/audit.ts provide programmatic access with Zod validation.
• Technical checks cover critical SEO signals including titles, meta descriptions, canonicals, indexability, broken links, and performance metrics.
• Audit results return structured JSON with page-level data, Lighthouse scores, and categorized issues suitable for UI rendering or CSV export.

Frequently Asked Questions

What types of technical SEO issues can OpenSEO detect?

OpenSEO detects missing titles, duplicate meta descriptions, broken internal links, redirect loops, canonical conflicts, indexability problems, and server response errors. The issue engine in src/server/lib/audit/issues/* runs both per-page and cross-page validations on normalized crawl data stored in D1.

How does OpenSEO respect robots.txt and crawling limits?

During the Discovery phase, OpenSEO parses robots.txt and XML sitemaps to identify crawlable URLs. The Crawl phase implements BFS (breadth-first search) restricted to same-origin URLs and enforces configurable page caps via the maxPages parameter, ensuring compliance with site constraints and plan limits.

Can OpenSEO audits be integrated into external applications?

Yes, the src/serverFunctions/audit.ts module exposes server functions that can be called programmatically from any application. These functions handle Zod-validated requests for starting audits, polling status, retrieving results, and deleting audits, making OpenSEO suitable for headless technical SEO audit implementations.

What performance data does OpenSEO collect during technical audits?

When lighthouseStrategy is set to 'auto', OpenSEO runs Google Lighthouse checks during the third workflow phase, capturing mobile and desktop performance scores, accessibility metrics, best practices scores, and SEO scores. These integrate with the technical issue data to provide comprehensive site health analysis.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}