Configuration

Frontguard is configured via frontguard.config.ts in your project root. Run frontguard init to generate a starter.

Full example

frontguard.config.ts

export default {
  version: 1,
  baseUrl: 'http://localhost:3000',

  // auto-discover routes (zero config)
  discover: { startUrl: '/', maxDepth: 3, exclude: ['/admin/*'] },

  viewports: [375, 768, 1440],
  browsers: ['chromium'],
  threshold: 0.1,

  // AI analysis (optional, BYOK)
  ai: { provider: 'openai', model: 'gpt-4o' },

  // anti-flake
  antiFlakeRenders: 2,
  freezeTime: true,

  ignore: [{ selector: '.dynamic-timestamp' }],
};

Core options

OptionDescriptionDefault

baseUrlRequired. Base URL of the app under test—

routesExplicit routes — strings or per-route objects—

discoverAuto-discovery configuration—

viewportsViewport widths in pixels[375,768,1440]

browserschromium · firefox · webkit['chromium']

thresholdMax allowed pixel diff as a fraction0.1

Per-route overrides

Different pages need different sensitivity. Any entry in routes can be an object instead of a plain string.

frontguard.config.ts

routes: [
  '/', // global threshold
  { path: '/checkout', threshold: 0.001 }, // strict — 0.1%
  { path: '/blog/*', threshold: 0.05 }, // lenient — 5%
  { path: '/gallery', viewport: [1440] }, // desktop only
]

Anti-flake options

antiFlakeRendersRenders per page for flake detection (recommended: 2–3).

freezeTimeFreeze Date.now() during render to stabilize timestamps.

ssimFallbackUse SSIM perceptual diff for borderline results.

renderRetriesPer-page retry count on render failure.

Set antiFlakeRenders: 2 to capture each page twice. If both renders differ from the baseline the diff is real; if only one does, it's a flake and gets ignored.