---
title: "How Unlighthouse Works · Unlighthouse"
canonical_url: "https://unlighthouse.dev/guide/getting-started/how-it-works"
last_updated: "2026-01-25T03:25:52Z"
meta:
  description: "Learn how Unlighthouse automatically discovers pages, runs Lighthouse audits in parallel, and generates site-wide performance reports."
  "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"
---

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**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

### 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:

```ts
const unlighthouse = await createUnlighthouse(config)
```

#### **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

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

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

#### **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**

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

#### **When It Starts**

Unlighthouse can start in two ways:

```ts
// CLI mode - starts immediately
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

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

#### **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**

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.

### **Related **

[**URL Discovery**](https://unlighthouse.dev/guide/guides/url-discovery) [**Configuration**](https://unlighthouse.dev/guide/guides/config) [**Core Web Vitals Glossary**](https://unlighthouse.dev/glossary)

[**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)