Getting Started
How It Works
Last updated by
Harlan Wilton
in chore: lint markdown. Introduction
Unlighthouse scans your website in a few simple steps. It finds all your pages, runs Lighthouse on each one, then shows you the results.
Here's how it works under the hood.
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:
- Route Files: Reads your framework's route files (like Next.js pages)
- Robots.txt: Checks your robots.txt file for sitemap links
- Sitemap.xml: Gets all URLs from your sitemap
- 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
- 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
Did this page help you?