---
title: "How Unlighthouse Works · Unlighthouse"
meta:
  "og:description": "Learn how Unlighthouse automatically discovers pages, runs Lighthouse audits in parallel, and generates site-wide performance reports."
  "og:title": "How Unlighthouse Works · Unlighthouse"
  description: "Learn how Unlighthouse automatically discovers pages, runs Lighthouse audits in parallel, and generates site-wide performance reports."
---

**Getting Started**

# **How Unlighthouse Works**

[Copy for LLMs](https://unlighthouse.dev/guide/getting-started/how-it-works.md)

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](#how-it-starts)

### [1. Setup](#_1-setup)

First, Unlighthouse loads your config file using the [**c12**](https://github.com/unjs/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](#browser-workers)

Unlighthouse creates a pool of Chrome browsers using [**puppeteer-cluster**](https://github.com/thomasdondorf/puppeteer-cluster):

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

### [2. Report Site Setup](#_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](#api)

The [**unrouted**](https://github.com/harlan-zw/unrouted) API handles:

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

#### [Web App](#web-app)

A [**Vite**](https://github.com/vitejs/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](#_3-the-actual-scanning)

#### [When It Starts](#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](#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

Having a sitemap.xml makes scanning much faster and finds more pages.

#### [What Happens to Each Page](#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**](https://unlighthouse.dev/glossary) like [**LCP**](https://unlighthouse.dev/glossary/lcp), [**CLS**](https://unlighthouse.dev/glossary/cls), [**INP**](https://unlighthouse.dev/glossary/inp))
- Saves the report as HTML and JSON files

#### [Live Updates](#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

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/1.getting-started/how-it-works.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/getting-started/how-it-works.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/1.getting-started/how-it-works.md) on GitHub or provide anonymous feedback below.

[**Integrations** Integrate Unlighthouse into your existing build tools, frameworks, and CI/CD pipelines for automated Lighthouse testing.](https://unlighthouse.dev/guide/getting-started/integrations) [**Configuration** Configure Unlighthouse for your specific needs using configuration files and inline options.](https://unlighthouse.dev/guide/guides/config)