---
title: "How Unlighthouse Works · Unlighthouse"
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"
---

</h1>

```

Unlighthouse on GitHub

**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:```
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~~**](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:```
// 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:```
// 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 linksHaving 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)