Guides

Configuration

Create unlighthouse.config.ts in your project root.

import { defineUnlighthouseConfig } from 'unlighthouse/config'

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

Run pnpm exec unlighthouse to use this config. Explicit CLI flags override configured values.

Config location

pnpm exec unlighthouse --root ./project --config-file unlighthouse.config.ts

root controls config lookup and relative output paths.

Select URLs and devices

import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  urls: ['/', '/about'],
  scanner: { device: 'desktop' },
})

Explicit urls disable link following. Supply a site when your URLs come from a provider function. Use --device mobile,desktop for a device matrix.

CI budgets

import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  ci: { reporter: 'json', budget: { performance: 80, accessibility: 90 } },
})

Run this config with pnpm exec unlighthouse-ci. Budgets use percentages from 1 to 100.

Authentication and browser settings

Use Authentication for headers, basic auth, and storage seeding. Use Chrome Options for supported browser settings. Legacy Puppeteer cluster options and config hooks are unsupported.