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:

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

Desktop Instead of Mobile

Default is mobile. Switch to desktop:

scanner: {
  device: 'desktop',
}

More Accurate Scores

Lighthouse scores vary between runs. For reliable numbers:

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)

// 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:

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:

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

React to Scan Events

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?

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.