Unlighthouse automates the entire site audit process: it finds all your pages, runs Lighthouse on each one in parallel, then shows you aggregated results in a real-time dashboard.

How It Starts

1. Setup

First, Unlighthouse loads your config file using the c12 package. This supports TypeScript config files and gives you a global defineUnlighthouseConfig function for type support:

const unlighthouse = await createUnlighthouse(config)

import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    samples: 3,
    throttle: true,
  },
})

Browser Workers

Unlighthouse creates a pool of Chrome browsers using puppeteer-cluster:

• Opens multiple Chrome instances
• Each one can scan a different page
• Runs scans in parallel to go faster

2. Report Site Setup

Unlighthouse starts a local web server so you can see the results:

// Create server for the UI client
const { server, app } = await createServer()
await unlighthouse.setServerContext({
  url: server.url,
  server: server.server,
  app
})

API

The unrouted API handles:

• Sending scan updates to your browser
• Serving Lighthouse reports
• Managing the scanning process

Web App

A Vite web app that:

• Shows scan progress in real-time
• Displays all the Lighthouse scores
• Lets you filter and explore results

3. The Actual Scanning

When It Starts

Unlighthouse can start in two ways:

// CLI mode - starts immediately
unlighthouse.start()

// Integration mode - waits for first client access
hooks.hookOnce('visited-client', () => {
  unlighthouse.start()
})

Finding Your Pages

Unlighthouse finds pages to scan in a few ways:

1. Route Files: Reads your framework's route files (like Next.js pages)
2. Robots.txt: Checks your robots.txt file for sitemap links
3. Sitemap.xml: Gets all URLs from your sitemap
4. Crawling: If no sitemap, it starts from your homepage and follows links

What Happens to Each Page

For every URL it finds, Unlighthouse does two things:

Step 1: Quick HTML Check

• Makes a simple HTTP request to get the HTML
• Grabs basic info like title, meta tags
• Looks for more links to scan

Step 2: Full Lighthouse Scan

• Opens the page in Chrome
• Runs all the Lighthouse tests (including Core Web Vitals like LCP, CLS, INP)
• Saves the report as HTML and JSON files

Live Updates

While scanning, the report page updates in real-time:

• Shows how many pages are done
• Updates the progress bar
• Shows results as soon as each page finishes