Guides

Configuration

Copy for LLMs

Most scans work without any config. But when you need control—excluding paths, adjusting concurrency, setting up auth—here's how.

The Config File

Create unlighthouse.config.ts in your project root:

import { defineUnlighthouseConfig } from 'unlighthouse/config'

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

Now run unlighthouse without flags. It picks up your config automatically.

The import is optional—skip it if you have resolution issues. The config still works.

Config File Location

Unlighthouse looks for these files in order:

  • unlighthouse.config.ts
  • unlighthouse.config.js
  • unlighthouse.config.mjs

Or specify one explicitly:

unlighthouse --config-file ./configs/production.config.ts

Common Configs

Skip Paths You Don't Care About

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    exclude: [
      '/api/*', // API routes
      '/admin/*', // Admin pages
      '/*.pdf', // PDF files
      '/amp/*', // AMP versions
    ],
  },
})

Or scan only specific paths:

export default {
  scanner: {
    include: ['/products/*', '/blog/*'], // Only these
  },
}

Desktop Instead of Mobile

Default is mobile. Switch to desktop:

export default {
  scanner: {
    device: 'desktop',
  },
}

More Accurate Scores

Lighthouse scores vary between runs. For reliable numbers:

export default {
  scanner: {
    samples: 3, // Run 3x per page, average the results
    throttle: true, // Simulate real network (slower but realistic)
  },
  puppeteerClusterOptions: {
    maxConcurrency: 1, // One at a time (less CPU contention)
  },
}

Trade-off: Much slower scans. Use for CI assertions, not development.

Protected Sites (Auth)

export default {
  // Basic auth
  auth: {
    username: process.env.AUTH_USER,
    password: process.env.AUTH_PASS,
  },

  // Cookie auth
  cookies: [
    { name: 'session', value: process.env.SESSION_TOKEN, domain: '.example.com' },
  ],
}

See full authentication guide.

CI Performance Budgets

Fail your build if scores drop:

export default {
  ci: {
    budget: {
      'performance': 80,
      'accessibility': 90,
      'best-practices': 80,
      'seo': 90,
    },
    buildStatic: true, // Generate shareable HTML report
  },
}

Advanced

Customize Lighthouse Directly

Pass options straight to Lighthouse:

export default {
  lighthouseOptions: {
    onlyCategories: ['performance', 'accessibility'], // Skip SEO/best-practices
    skipAudits: ['uses-http2'], // Ignore specific audits
    throttlingMethod: 'devtools',
  },
}

React to Scan Events

export default {
  hooks: {
    'task-complete': (path, report) => {
      if (report.score.performance < 0.5) {
        console.warn(`⚠️ ${path} scored ${report.score.performance}`)
      }
    },
    'worker-finished': () => {
      console.log('All done!')
    },
  },
}

Environment-Based Config

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

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

Full Reference

See Config Reference for every option with types and defaults.

Edit this page
Markdown For LLMs
Did this page help you?
Anything that could be done better? :)
Help us improve this page. You can edit this page on GitHub or provide anonymous feedback below.

How It Works

Learn how Unlighthouse automatically discovers pages, runs Lighthouse audits in parallel, and generates site-wide performance reports.

Debugging

Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools.