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

> Discover Open-SEO audit system configuration options including maxPages and lighthouseStrategy. Master your crawl limits and performance analysis with this complete AuditConfig guide.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts), the workflow monitors the crawl count against this limit:

```typescript
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:

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/every-app/open-seo/blob/main/src/server/lib/audit/types.ts):

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.