Configuration

Configuration Files

Web Guard looks for configuration in the following order:

web-guard.config.ts
web-guard.config.js
web-guard.config.json
web-guard field in package.json

Configuration Interface

typescript

interface WebGuardConfig {
  url: string;
  device?: "mobile" | "desktop";          // Default: "mobile"
  preset?: string;                         // "lenient" | "recommended" | "strict"
  pillars?: PillarName[];                  // Default: all 6

  performance?: {
    minScore?: number;                     // Default: 80
    lcp?: number;                          // Default: 2500 (ms)
    cls?: number;                          // Default: 0.1
    inp?: number;                          // Default: 200 (ms)
    ttfb?: number;                         // Default: 800 (ms)
    fcp?: number;                          // Default: 1800 (ms)
    ignoreSeverities?: Severity[];
  };

  a11y?: {
    minScore?: number;                     // Default: 80
    ignoreSeverities?: Severity[];
  };

  seo?: {
    minScore?: number;                     // Default: 80
    ignoreSeverities?: Severity[];
  };

  schema?: {
    minScore?: number;                     // Default: 80
    ignoreSeverities?: Severity[];
  };

  security?: {
    minScore?: number;                     // Default: 80
    ignoreSeverities?: Severity[];
  };

  ux?: {
    minScore?: number;                     // Default: 80
    ignoreSeverities?: Severity[];
  };
}

type Severity = "critical" | "serious" | "moderate" | "minor";
type PillarName = "performance" | "a11y" | "seo" | "schema" | "security" | "ux";

Example Configuration File

typescript

// web-guard.config.ts
export default {
  url: "https://your-site.com",
  device: "mobile",
  preset: "recommended",

  performance: {
    minScore: 85,
    lcp: 2500,
    cls: 0.1,
  },

  a11y: {
    minScore: 90,
    ignoreSeverities: ["minor"],
  },

  seo: {
    minScore: 80,
  },
};

Package.json Configuration

json

{
  "name": "my-project",
  "version": "1.0.0",
  "web-guard": {
    "url": "https://your-site.com",
    "preset": "recommended",
    "pillars": ["performance", "a11y", "seo"]
  }
}

Config Priority

Configuration values are merged in this order (highest priority first):

CLI arguments (--url, --device, --pillars, etc.)
Config file (web-guard.config.ts/js/json)
package.json "web-guard" field
Preset values (if --preset is used)
Built-in defaults

CLI arguments always win. This lets you override config file values for specific CI jobs or local testing.

CLI Usage Presets