Install Unlighthouse

Use Node.js 24.13.1 or newer, with npm available for first-use downloads. 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. Lighthouse and browser tooling download before the first audit. The default audit download uses native HTTP and verifies the pinned archive hash. Configured npm registries, credentials, proxies, and certificates use npm instead. Any detected .npmrc file also selects npm, even if it contains unrelated options. Set UNLIGHTHOUSE_RUNTIME_URL to download the same archive from your own mirror. The mirror must serve the matching runtime package tarball. Mirror URLs cannot include a username or password. Use npm configuration for authenticated downloads. If Chrome is unavailable, Unlighthouse downloads it too. The dashboard downloads when you open it or export a static report. Set UNLIGHTHOUSE_RUNTIME_CACHE to choose the shared dependency cache. Use a private directory owned by your account. On Linux and macOS, use permissions 0700 for the cache directory. Parent directories cannot allow writes from other accounts. If an older cache fails this check, choose a new private path:

UNLIGHTHOUSE_RUNTIME_CACHE="$HOME/.unlighthouse-runtime" pnpm exec unlighthouse --site https://example.com

For a Chrome cache failure, set chrome.downloadFallbackCacheDir to a new private directory in your configuration. UNLIGHTHOUSE_RUNTIME_CACHE cannot override an explicit Chrome cache path.

See Chrome Dependency for browser and cache options.

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.

Source development

Run pnpm dev:cli --help from the repository root. The development scripts build the audit runtime before starting the CLI.