Open-SEO Audit System Configuration Options: A Complete Guide to AuditConfig

The open-seo audit system utilizes a compact, typed AuditConfig object containing two adjustable parameters—maxPages (enforcing crawl limits between 10 and 5,000 pages) and lighthouseStrategy (toggling Lighthouse performance analysis between "auto" and "none")—to control every aspect of the crawling and analysis workflow.

The open-seo audit engine from every-app/open-seo is driven by a JSON-driven configuration layer that balances flexibility with type safety. At runtime, the system parses a stored AuditConfig object to determine crawling scope and analysis depth. Understanding these configuration options enables precise control over audit duration, resource consumption, and the breadth of SEO data collected.

Understanding the AuditConfig Interface

Core Configuration Structure

The configuration contract is defined in src/server/lib/audit/types.ts, where the AuditConfig interface establishes the schema for all audit behavior. This interface is intentionally minimal, exposing only the essential parameters needed to control the audit workflow:

// https://github.com/every-app/open-seo/blob/main/src/server/lib/audit/types.ts
export interface AuditConfig {
  maxPages: number;               // controlled by audit-limits constants
  lighthouseStrategy: LighthouseStrategy;
}

Type Safety with Zod Validation

To guarantee runtime type safety and backward compatibility, the codebase implements a Zod schema called auditConfigSchema. This schema enforces numeric ranges for maxPages and handles graceful enum transformations for legacy values. The schema maps deprecated inputs—such as converting "all" to "auto" and "manual" to "none"—ensuring older audits remain functional even after the enum is trimmed.

Available Configuration Options

maxPages: Crawl Limits and Validation

The maxPages parameter accepts an integer between platform-wide limits defined in src/shared/audit-limits.ts. The minimum threshold is MIN_AUDIT_PAGES (currently 10), while the upper bound is PAID_MAX_AUDIT_PAGES (currently 5,000). This validation prevents runaway crawls and supports tiered pricing models by enforcing hard stops when the page limit is reached.

During execution in src/server/workflows/SiteAuditWorkflow.ts, the workflow monitors the crawl count against this limit:

if (pagesCrawled >= parsedConfig?.maxPages) {
  // stop crawling further pages
}

lighthouseStrategy: Performance Analysis Control

This field accepts either "auto" or "none", determining whether the Lighthouse performance analyzer runs during the audit. When set to "auto", the system executes mobile-only Lighthouse checks on each crawled page and injects performance metrics into the results. Setting the value to "none" bypasses performance analysis entirely, which is ideal for rapid structural SEO audits or cost-sensitive operations.

The SiteAuditWorkflow checks this setting before initializing Lighthouse:

if (parsedConfig?.lighthouseStrategy !== "none") {
  // run Lighthouse checks
}

Implementation in the Open-SEO Codebase

Creating Audits with AuditService

When an audit is instantiated, the AuditService located in src/server/features/audit/services/AuditService.ts constructs the configuration object from the incoming request payload or applies sensible defaults. The service then persists the configuration as a JSON string on the audit record:

// https://github.com/every-app/open-seo/blob/main/src/server/features/audit/services/AuditService.ts
const config: AuditConfig = {
  maxPages,                     // supplied by the client, validated upstream
  lighthouseStrategy,
};
await AuditRepository.createAudit({ …, config: JSON.stringify(config) });

Runtime Parsing in SiteAuditWorkflow

During the audit execution phase, the SiteAuditWorkflow retrieves the stored JSON configuration and parses it using the parseAuditConfig helper function from src/server/lib/audit/types.ts. This parsing step reconstructs the typed AuditConfig object, allowing workflow steps to make runtime decisions based on the original configuration intent.

Practical Configuration Examples

Creating an Audit with Custom Settings

To initiate an audit with a specific page limit and disabled performance analysis, include the configuration options in your API request:

import { fetch } from "open-seo-client";

await fetch("/api/audit", {
  method: "POST",
  body: JSON.stringify({
    projectId: "proj_123",
    startUrl: "https://example.com",
    // -----------------------------------------------------------------
    // Configuration options:
    maxPages: 200,                // crawl up to 200 pages
    lighthouseStrategy: "none",  // skip performance analysis
    // -----------------------------------------------------------------
  }),
});

Accessing Configuration in Custom Workflow Steps

Developers can extract and inspect the audit configuration within custom workflow steps to conditionally execute logic:

import { parseAuditConfig } from "@/server/lib/audit/types";

export async function myCustomStep(auditId: string) {
  const audit = await AuditRepository.getAudit(auditId);
  const cfg = parseAuditConfig(audit.config);
  console.log(`Audit ${auditId} will crawl up to ${cfg?.maxPages} pages`);
  if (cfg?.lighthouseStrategy === "none") {
    console.log("Lighthouse checks are disabled for this audit");
  }
}

Extending the Configuration Schema

The configuration system is designed for evolution. To add new options—such as a crawlDepth limit—modify the interface and Zod schema in src/server/lib/audit/types.ts:

// In src/server/lib/audit/types.ts
export interface AuditConfig {
  maxPages: number;
  lighthouseStrategy: LighthouseStrategy;
  crawlDepth?: number;          // optional new field
}

// Update Zod schema
const auditConfigSchema = z.object({
  maxPages: z.number().int().min(MIN_AUDIT_PAGES).max(PAID_MAX_AUDIT_PAGES),
  lighthouseStrategy: lighthouseStrategySchema,
  crawlDepth: z.number().int().min(1).max(10).optional(),
});

Summary

• The open-seo audit system configuration options are defined by the AuditConfig interface in src/server/lib/audit/types.ts.
• The maxPages setting enforces hard boundaries between MIN_AUDIT_PAGES (10) and PAID_MAX_AUDIT_PAGES (5,000) to control crawl scope.
• The lighthouseStrategy field accepts "auto" for full performance analysis or "none" for structural-only audits, with automatic backward compatibility for legacy enum values.
• Configuration objects are serialized to JSON by AuditService and parsed at runtime by parseAuditConfig within the SiteAuditWorkflow.
• Zod schema validation ensures type safety and prevents invalid configurations from entering the execution pipeline.

Frequently Asked Questions

What is the maximum number of pages I can audit in open-seo?

The open-seo audit system enforces a hard limit of 5,000 pages per audit, defined by the PAID_MAX_AUDIT_PAGES constant in src/shared/audit-limits.ts. The minimum crawl size is 10 pages (MIN_AUDIT_PAGES), ensuring meaningful SEO analysis while preventing system abuse through micro-crawls.

How do I disable Lighthouse performance checks in an audit?

Set the lighthouseStrategy configuration option to "none" when creating the audit via the API. This skips the mobile Lighthouse analysis on all crawled pages, significantly reducing audit execution time and resource consumption while still collecting structural SEO data such as meta tags and heading hierarchies.

Where is the audit configuration stored in the database?

The AuditService stores the configuration as a JSON string on the audit row in the database. During execution, the SiteAuditWorkflow retrieves this string and parses it using the parseAuditConfig helper function from src/server/lib/audit/types.ts to reconstruct the typed configuration object for runtime decision-making.

Does open-seo support legacy configuration values?

Yes, the Zod schema in src/server/lib/audit/types.ts includes transforms that map deprecated values to current equivalents. For example, legacy values of "all" automatically convert to "auto", and "manual" converts to "none", ensuring older audits remain viewable and functional even after the configuration schema is updated.

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