Guides

Configuration

Copy for LLMs
Last updated by
Harlan Wilton
 in chore: deprecate integrations.

Introduction

Unlighthouse provides flexible configuration options to customize scanning behavior, performance settings, and report generation. While each integration supports inline configuration, complex projects benefit from dedicated configuration files.

This guide covers configuration file setup, common patterns, and advanced customization options.

Configuration File

File Discovery

Unlighthouse automatically discovers configuration files in your project root:

  • Default: unlighthouse.config.ts
  • Custom: Use configFile option or --config-file CLI flag

Basic Configuration

unlighthouse.config.ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    exclude: ['/private/*']
  },
  debug: true,
})
If the unlighthouse/config package has issues resolving you can safely remove the import.

Configuration Options

For a complete list of configuration options, see the Config Reference.

Common Configuration Patterns

Performance Optimization

Optimize scanning for large sites:

import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://large-site.com',
  scanner: {
    device: {
      concurrency: 3,
    },
    samples: 3,
    throttle: true,
    maxRoutes: 100,
  },
})

Route Filtering

Exclude specific patterns from scanning:

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    exclude: [
      '/api/**',
      '/**/*.pdf',
      '/**/amp',
      '/admin/**',
    ],
    include: ['/products/**'],
  },
})

Device Configuration

Customize viewport and user agent:

export default defineUnlighthouseConfig({
  scanner: {
    device: 'desktop', // or 'mobile'
    // Custom device settings
    customDevice: {
      viewport: {
        width: 1920,
        height: 1080,
      },
      userAgent: 'Custom User Agent String',
    },
  },
})

Authentication Setup

Configure authentication for protected sites:

export default defineUnlighthouseConfig({
  scanner: {
    // Basic auth
    auth: {
      username: process.env.AUTH_USER,
      password: process.env.AUTH_PASS,
    },
    // Cookies for session auth
    cookies: [
      {
        name: 'session',
        value: process.env.SESSION_TOKEN,
        domain: '.example.com',
      },
    ],
  },
})

CI/CD Configuration

Optimize for continuous integration:

export default defineUnlighthouseConfig({
  ci: {
    // Generate static reports
    buildStatic: true,
    // Set performance budgets
    budget: {
      'performance': 90,
      'accessibility': 95,
      'best-practices': 90,
      'seo': 90,
    },
  },
  scanner: {
    // Faster scans for CI
    samples: 1,
    throttle: false,
  },
})

Advanced Configuration

Custom Lighthouse Configuration

Extend Lighthouse's default configuration:

export default defineUnlighthouseConfig({
  lighthouseOptions: {
    // Custom Lighthouse flags
    onlyCategories: ['performance', 'accessibility'],
    // Disable specific audits
    skipAudits: ['uses-http2'],
    // Custom gathering settings
    throttlingMethod: 'devtools',
  },
})

Hook System

Respond to scanning events:

export default defineUnlighthouseConfig({
  hooks: {
    'reporter:done': (reports) => {
      console.log(`Scanned ${reports.length} pages`)
    },
    'task:complete': (result) => {
      if (result.report.score.performance < 0.5) {
        console.warn(`Poor performance: ${result.route.path}`)
      }
    },
  },
})

Dynamic Configuration

Generate configuration based on environment:

export default defineUnlighthouseConfig(() => {
  const isProduction = process.env.NODE_ENV === 'production'

  return {
    site: isProduction
      ? 'https://production.com'
      : 'http://localhost:3000',
    scanner: {
      samples: isProduction ? 3 : 1,
      throttle: isProduction,
    },
  }
})

For complete configuration options, refer to the API Config Reference.

Edit this page
Markdown For LLMs
Did this page help you?

How It Works

How Unlighthouse scans your site - the simple explanation.

Debugging

Learn how to debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools.