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

> Learn to configure site audit settings in OpenSEO. Customize maximum pages and Lighthouse strategy for tailored performance checks. Maximize your SEO efforts with this guide.

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

---

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

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

```

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

```ts
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](https://github.com/every-app/open-seo/blob/main/src/client/features/audit/launch/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`](https://github.com/every-app/open-seo/blob/main/src/server/features/audit/services/AuditService.ts) (lines 55-69):

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

```

*(source: [AuditService.ts#L55-L69](https://github.com/every-app/open-seo/blob/main/src/server/features/audit/services/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`](https://github.com/every-app/open-seo/blob/main/src/db/audit.schema.ts) (lines 31-33):

*(source: [audit.schema.ts#L31-L33](https://github.com/every-app/open-seo/blob/main/src/db/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:

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

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

### Method 3: Retrieving Stored Configuration

Inspect what was actually persisted:

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

```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`](https://github.com/every-app/open-seo/blob/main/src/client/features/audit/launch/types.ts) | `getMaxPagesLimit` | Sets `max` attribute on UI input |
| Server enforcement | [`src/server/lib/audit/audit-capacity.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.