How to Configure Site Audit Settings in OpenSEO: A Complete Guide

OpenSEO allows you to configure maximum pages and Lighthouse strategy for each site audit, with different limits based on your plan tier and full control over performance checks.

OpenSEO is an open-source SEO auditing platform built for Cloudflare Workers. In this guide, you'll learn exactly how to configure site audit settings, where these configurations live in the codebase, and how to customize them for your deployment.

Understanding Audit Configuration Parameters

Every OpenSEO site audit is controlled by two parameters stored in the AuditConfig interface:

Parameter	Purpose	Available Values
maxPages	Maximum URLs the crawler will fetch	1 to plan limit (50 for free, 10,000 for paid)
lighthouseStrategy	Whether to run Lighthouse performance audits	"auto" (run checks) or "none" (skip checks)

These values are defined in src/server/lib/audit/types.ts:

export interface AuditConfig {
  maxPages: number;
  lighthouseStrategy: LighthouseStrategy;
}

(source: types.ts#L11-L14)

Where Configuration Lives in the Codebase

Client-Side: The Launch Form

The useLaunchController hook in src/client/features/audit/launch/useLaunchController.ts handles UI input validation and prepares the audit payload.

Here's how it processes your settings (lines 70-88):

const result = await startMutation.mutateAsync({
  projectId,
  startUrl: value.url,
  maxPages: effectiveMaxPages,                     // capped to plan limit
  lighthouseStrategy: value.runLighthouse ? "auto" : "none",
});

(source: useLaunchController.ts#L70-L88)

The form automatically:

• Clamps maxPages to your tier limit via getMaxPagesLimit
• Converts the "Run Lighthouse" checkbox to the proper strategy string

Server-Side: AuditService Processing

The AuditService.startAudit method validates and persists your configuration. From src/server/features/audit/services/AuditService.ts (lines 55-69):

const maxPages = clampAuditMaxPages(input.maxPages);
const lighthouseStrategy = input.lighthouseStrategy ?? "auto";
const config: AuditConfig = { maxPages, lighthouseStrategy };
await AuditRepository.createAudit({ ..., config, ... });

(source: AuditService.ts#L55-L69)

The server enforces hard caps through clampAuditMaxPages and throws AUDIT_PAGE_LIMIT_EXCEEDED if you exceed your plan's maxPagesPerAudit quota.

Database Storage

The complete configuration is stored as JSON in the config column of the audit table, defined in src/db/audit.schema.ts (lines 31-33):

(source: audit.schema.ts#L31-L33)

How to Configure Site Audit Settings: 4 Methods

Method 1: Using the React UI (Default)

Import useLaunchController to build a compliant launch form:

import { useLaunchController } from "@/client/features/audit/launch/useLaunchController";

function AuditLauncher({ projectId, isFreePlan, onAuditStarted }) {
  const {
    launchForm,
    maxPagesLimit,
    commitMaxPagesInput,
  } = useLaunchController({ projectId, isFreePlan, onAuditStarted });

  return (
    <form onSubmit={launchForm.handleSubmit}>
      <input name="url" placeholder="https://example.com" />
      <input
        name="maxPagesInput"
        type="number"
        min={1}
        max={maxPagesLimit}
        placeholder={String(maxPagesLimit)}
      />
      <label>
        <input type="checkbox" name="runLighthouse" />
        Run Lighthouse checks
      </label>
      <button type="submit">Start audit</button>
    </form>
  );
}

The hook automatically caps input values and maps the checkbox to "auto"/"none".

Method 2: Programmatic API Call

Call the server function directly with explicit configuration:

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

async function startCustomAudit() {
  const result = await startAudit({
    data: {
      projectId: "proj_123",
      startUrl: "https://my-site.com",
      maxPages: 200,                    // will be validated against plan limit
      lighthouseStrategy: "auto",       // or "none" to skip
    },
  });
  console.log("Audit started, ID:", result.auditId);
}

The payload validates against startAuditSchema in src/types/schemas/audit.ts.

Method 3: Retrieving Stored Configuration

Inspect what was actually persisted:

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

async function fetchAuditConfig(auditId: string) {
  const { audit } = await getAuditResults({ data: { auditId } });
  console.log("Audit config:", audit.config);
  // { maxPages: 200, lighthouseStrategy: "auto" }
}

Method 4: Self-Hosted Deployment Overrides

Modify tier limits in src/shared/audit-limits.ts:

// src/shared/audit-limits.ts
export const FREE_MAX_AUDIT_PAGES = 100;     // default: 50
export const PAID_MAX_AUDIT_PAGES = 15000;   // default: 10000

After rebuilding, both client and server enforce your new defaults automatically.

Plan Limits and Enforcement Logic

OpenSEO applies tier-based caps through two mechanisms:

Mechanism	File	Function	Purpose
Client validation	src/client/features/audit/launch/types.ts	getMaxPagesLimit	Sets max attribute on UI input
Server enforcement	src/server/lib/audit/audit-capacity.ts	clampAuditMaxPages	Hard caps and error throwing
Capacity check	AuditService.startAudit	Plan comparison	Throws AUDIT_PAGE_LIMIT_EXCEEDED

The constants themselves live in src/shared/audit-limits.ts and are shared across client and server bundles.

Summary

• Two settings control every audit: maxPages (crawl depth) and lighthouseStrategy (performance checks).
• Client UI gathers input via useLaunchController and pre-validates against tier limits.
• Server finalizes configuration in AuditService.startAudit, clamps values, and persists JSON to the database.
• Plan limits are enforced at multiple layers and defined in src/shared/audit-limits.ts.
• Self-hosted deployments can override defaults by editing shared constants before building.

Frequently Asked Questions

What happens if I request more pages than my plan allows?

The server throws an AUDIT_PAGE_LIMIT_EXCEEDED error during AuditService.startAudit. The client UI prevents this by clamping the input field's maximum value to your tier limit.

Can I change the Lighthouse strategy after starting an audit?

No. The lighthouseStrategy is immutable once stored in audit.config. You must start a new audit with different parameters.

Where is the audit configuration actually stored?

As JSON in the config column of the audit table, defined in src/db/audit.schema.ts. Retrieve it via getAuditResults or directly from your database.

How do I increase limits for my self-hosted OpenSEO instance?

Edit src/shared/audit-limits.ts to modify FREE_MAX_AUDIT_PAGES and PAID_MAX_AUDIT_PAGES, then rebuild and redeploy. Both client and server automatically pick up the new values.

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