Install Unlighthouse

Use Node.js 24.13.1 or newer and an installed Chrome browser. Install the v1 beta in your project:

pnpm add -D unlighthouse@beta
pnpm exec unlighthouse --site https://example.com

For a one-time scan, run:

pnpm dlx unlighthouse@beta --site https://example.com

The CLI discovers routes, runs Lighthouse, and opens the dashboard. The beta package also includes the CI runner and MCP executable.

Project configuration

Create unlighthouse.config.ts in your project root:

import { defineUnlighthouseConfig } from 'unlighthouse/config'

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

Then run pnpm exec unlighthouse without a site flag. Unlighthouse keeps the median audit when you request multiple samples.

Discovery limits

The crawler reads links from server-rendered HTML. For JavaScript-rendered links, supply a sitemap or explicit urls. Use scanner.maxRoutes to bound the scan.

CI and history

pnpm exec unlighthouse-ci --site https://example.com --reporter json
pnpm exec unlighthouse --history

The CI runner exits after the scan and report export. --history opens the dashboard without starting a scan.

Upgrade from 0.x

Read Migrating to v1 before changing custom integrations. Use the documentation version switcher to view the 0.x instructions.