## Quick Setup
Run the following command:
```bash
npx unlighthouse --site
# or PNPM
pnpm dlx unlighthouse --site
```
> [!TIP]
> Using an AI agent? Get the unlighthouse Skill on [skilld.dev/gh/harlan-zw/unlighthouse](https://skilld.dev/gh/harlan-zw/unlighthouse).
_Requirements: Node >= 22.18.0._
## Getting Started
Install instructions for all integrations can be found on the [docs](https://unlighthouse.dev/) site.
Need a hand? Join the [Discord](https://discord.gg/275MBUBvgP) for one-on-one help.
### gitignore
Unlighthouse will save your reports in `outputDir`,
it's recommended you .gitignore these files.
```shell
.unlighthouse
```
#### Debugging
If you run into any issues with Unlighthouse, the first step should be to re-run the scan with debugging enabled.
```bash
# NPM
npx unlighthouse --site unlighthouse.dev --debug
# or PNPM
pnpm dlx unlighthouse --site unlighthouse.dev --debug
```
## Docs
Integration instructions, Guides, API and config spec can be found on [docs](https://unlighthouse.dev/) site.
## Sponsors
You can manually provide a project mapping for [routes definitions](/guide/guides/route-definitions). |
| [CI](/integrations/ci) | Run scans on sites based on automation events, i.e releasing and make [assertions on scores](/integrations/ci#assertions).
Can also be used to generate report sites such as [inspect.unlighthouse.dev](https://inspect.unlighthouse.dev/). |
## Build tools / Frameworks
::warning
**Deprecation Notice**: Build tool integrations are deprecated and will be removed in v1.0. We recommend using the CLI or CI integrations instead. [Learn more about deprecations](/integration-deprecations)
::
| Provider | Features |
|----------|----------|
| [Nuxt.js](/integrations/nuxt) | Hot Module Reloading, Automatic Route Discovery |
| [Vite](/integrations/vite) | Hot Module Reloading, Automatic Route Discovery |
| [webpack](/integrations/webpack) | Hot Module Reloading |
---
### 1.Guide 1.Getting Started How It Works (`docs/1.guide/1.getting-started/how-it-works.md`)
---
title: "How Unlighthouse Works"
description: "Learn how Unlighthouse automatically discovers pages, runs Lighthouse audits in parallel, and generates site-wide performance reports."
keywords:
- how unlighthouse works
- lighthouse site scanner
- automated lighthouse testing
- site-wide lighthouse audit
- bulk lighthouse scan
- parallel lighthouse testing
navigation:
title: "How It Works"
relatedPages:
- path: /guide/guides/url-discovery
title: URL Discovery
- path: /guide/guides/config
title: Configuration
- path: /glossary
title: Core Web Vitals Glossary
---
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:
::code-group
```ts [Configuration Loading]
const unlighthouse = await createUnlighthouse(config)
```
```ts [unlighthouse.config.ts]
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:
```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:
::code-group
```ts [Immediate Start]
// CLI mode - starts immediately
unlighthouse.start()
```
```ts [Lazy 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
::tip
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](/glossary) like [LCP](/glossary/lcp), [CLS](/glossary/cls), [INP](/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
---
### 1.Guide Guides 0.Config (`docs/1.guide/guides/0.config.md`)
---
title: "Configuration"
description: "Configure Unlighthouse for your specific needs using configuration files and inline options."
keywords:
- unlighthouse config
- unlighthouse configuration
- unlighthouse.config.ts
- lighthouse config file
- lighthouse settings
navigation:
title: "Configuration"
relatedPages:
- path: /api-doc/config
title: Config Reference
- path: /guide/guides/debugging
title: Debugging
- path: /integrations/cli
title: CLI Integration
---
Most scans work without any config. But when you need control—excluding paths, adjusting concurrency, setting up auth—here's how.
## The Config File
Create `unlighthouse.config.ts` in your project root:
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
site: 'https://example.com',
scanner: {
exclude: ['/admin/*', '/api/*'],
},
})
```
Now run `unlighthouse` without flags. It picks up your config automatically.
::tip
The import is optional—skip it if you have resolution issues. The config still works.
::
## Config File Location
Unlighthouse looks for these files in order:
- `unlighthouse.config.ts`
- `unlighthouse.config.js`
- `unlighthouse.config.mjs`
Or specify one explicitly:
```bash
unlighthouse --config-file ./configs/production.config.ts
```
## Common Configs
### Skip Paths You Don't Care About
```ts
export default defineUnlighthouseConfig({
site: 'https://example.com',
scanner: {
exclude: [
'/api/**', // API routes
'/admin/**', // Admin pages
'/amp/**', // AMP versions
],
},
})
```
Or scan *only* specific paths:
```ts
export default defineUnlighthouseConfig({
scanner: {
include: ['/', '/products/**', '/blog/**'], // Only these, keep '/' so the crawler can start
},
})
```
### Desktop Instead of Mobile
Default is mobile. Switch to desktop:
```ts
export default defineUnlighthouseConfig({
scanner: {
device: 'desktop',
},
})
```
### More Accurate Scores
Lighthouse scores vary between runs. For reliable numbers:
```ts
export default defineUnlighthouseConfig({
scanner: {
samples: 3, // Run 3x per page, average the results
throttle: true, // Simulate real network (slower but realistic)
},
puppeteerClusterOptions: {
maxConcurrency: 1, // One at a time (less CPU contention)
},
})
```
Trade-off: Much slower scans. Use for CI assertions, not development.
### Protected Sites (Auth)
```ts
export default defineUnlighthouseConfig({
// Basic auth
auth: {
username: process.env.AUTH_USER,
password: process.env.AUTH_PASS,
},
// Cookie auth
cookies: [
{ name: 'session', value: process.env.SESSION_TOKEN, domain: '.example.com' },
],
})
```
See [full authentication guide](/guide/guides/authentication).
### CI Performance Budgets
Fail your build if scores drop:
```ts
export default defineUnlighthouseConfig({
ci: {
budget: {
'performance': 80,
'accessibility': 90,
'best-practices': 80,
'seo': 90,
},
buildStatic: true, // Generate shareable HTML report
},
})
```
## Advanced
### Customize Lighthouse Directly
Pass options straight to Lighthouse:
```ts
export default defineUnlighthouseConfig({
lighthouseOptions: {
onlyCategories: ['performance', 'accessibility'], // Skip SEO/best-practices
skipAudits: ['uses-http2'], // Ignore specific audits
throttlingMethod: 'devtools',
},
})
```
### React to Scan Events
```ts
export default defineUnlighthouseConfig({
hooks: {
'task-complete': (path, report, taskName) => {
// fires for each task; only the Lighthouse task has scores
if (taskName !== 'runLighthouseTask')
return
const performance = report.report?.categories.find(category => category.key === 'performance')
if (performance?.score != null && performance.score < 0.5)
console.warn(`⚠️ ${path} scored ${performance.score}`)
},
'worker-finished': () => {
console.log('All done!')
},
},
})
```
### Environment-Based Config
```ts
export default defineUnlighthouseConfig(() => {
const isProd = process.env.NODE_ENV === 'production'
return {
site: isProd ? 'https://mysite.com' : 'http://localhost:3000',
scanner: {
samples: isProd ? 3 : 1,
throttle: isProd,
},
}
})
```
## Full Reference
See [Config Reference](/api-doc/config) for every option with types and defaults.
---
### 1.Guide Guides 1.Debugging (`docs/1.guide/guides/1.debugging.md`)
---
title: "Debugging Lighthouse Scans"
description: "Debug and troubleshoot Unlighthouse scans using logging, browser inspection, and diagnostic tools."
keywords:
- lighthouse debug
- lighthouse troubleshooting
- lighthouse not working
- puppeteer debug
- lighthouse scan failing
navigation:
title: "Debugging"
relatedPages:
- path: /guide/guides/common-errors
title: Common Errors
- path: /guide/guides/config
title: Configuration
- path: /guide/guides/puppeteer
title: Puppeteer Configuration
---
Scan not working? Here's how to figure out why.
## Start Here: Debug Logs
90% of issues become obvious with debug logging:
```bash
unlighthouse --site example.com --debug
```
This shows you:
- What URLs are being discovered
- Which pages are being scanned
- Any errors or timeouts
- Chrome connection status
## Watch the Browser
Can't tell what's happening? Watch it:
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
headless: false, // Show the browser window
slowMo: 250, // Slow down so you can see what's happening
devtools: true, // Open Chrome DevTools
},
puppeteerClusterOptions: {
maxConcurrency: 1, // One page at a time
},
})
```
Now you'll see exactly what Unlighthouse sees—useful for:
- Auth issues (is login working?)
- JavaScript errors (check the console)
- Missing content (is the page rendering?)
- Blocked requests (check Network tab)
::warning
Visual mode is slow. Only use it to diagnose specific problems.
::
## Common Issues
### Pages Timing Out
Your site might be slow or have heavy JavaScript:
```ts
export default defineUnlighthouseConfig({
lighthouseOptions: {
maxWaitForLoad: 60000, // Wait up to 60s (default: 45s)
},
})
```
### SPA Not Rendering
JavaScript apps need time to hydrate:
```ts
export default defineUnlighthouseConfig({
scanner: {
skipJavascript: false, // Wait for JS to execute
},
lighthouseOptions: {
maxWaitForLoad: 45000,
},
})
```
### SSL/Certificate Errors
On localhost or staging with self-signed certs:
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
ignoreHTTPSErrors: true,
args: ['--ignore-certificate-errors'],
},
})
```
### Chrome Won't Start
Try using bundled Chromium instead of system Chrome:
```ts
export default defineUnlighthouseConfig({
chrome: {
useSystem: false, // Download and use bundled Chromium
},
})
```
Or point to a specific Chrome:
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
executablePath: '/usr/bin/google-chrome-stable',
},
})
```
### Failed Network Requests
Log all failed requests to find what's breaking:
```ts
export default defineUnlighthouseConfig({
hooks: {
'puppeteer:before-goto': async (page) => {
page.on('requestfailed', (req) => {
console.log('❌ Failed:', req.url(), req.failure()?.errorText)
})
},
},
})
```
## Still Stuck?
1. Check [Common Errors](/guide/guides/common-errors) for known issues
2. Search [GitHub Issues](https://github.com/harlan-zw/unlighthouse/issues)
3. Ask on [Discord](https://discord.gg/275MBUBvgP) with your debug logs
---
### 1.Guide Guides Authentication (`docs/1.guide/guides/authentication.md`)
---
title: "Authentication for Lighthouse Scans"
description: "Scan password-protected websites with Unlighthouse. Configure basic auth, cookies, headers, localStorage, and programmatic login flows."
keywords:
- lighthouse authentication
- lighthouse password protected
- lighthouse login
- puppeteer authentication
- lighthouse behind login
- scan authenticated pages
navigation:
title: "Authentication"
relatedPages:
- path: /guide/guides/debugging
title: Debugging
- path: /guide/guides/puppeteer
title: Puppeteer Configuration
- path: /guide/guides/config
title: Configuration
---
Need to scan pages behind a login? Unlighthouse supports every common auth pattern. Find yours below.
## Quick Reference
| Auth Type | Best For | Config Key |
|-----------|----------|------------|
| Basic Auth | Staging environments with HTTP basic auth | `auth` |
| Cookies | Session tokens, JWTs in cookies | `cookies` |
| Headers | Bearer tokens, API keys | `extraHeaders` |
| localStorage | SPAs storing tokens in localStorage | `localStorage` |
| Programmatic | Complex login flows, 2FA | `hooks.authenticate` |
## Basic Auth
For sites using HTTP Basic Authentication (the browser popup):
```ts
export default defineUnlighthouseConfig({
auth: {
username: process.env.AUTH_USER,
password: process.env.AUTH_PASS,
},
})
```
Or via CLI:
```bash
unlighthouse --site staging.example.com --auth admin:secretpass
```
## Cookies
Most common for session-based auth. Grab your session cookie from browser DevTools (Application → Cookies):
```ts
export default defineUnlighthouseConfig({
cookies: [
{
name: 'session_id',
value: 'abc123...',
domain: 'example.com', // Must match your site
path: '/',
},
],
})
```
**Getting the cookie value:**
1. Log into your site in Chrome
2. Open DevTools → Application → Cookies
3. Copy the session cookie value
4. Paste into config (or use environment variable)
CLI shorthand:
```bash
unlighthouse --site example.com --cookies "session_id=abc123"
# Multiple cookies
unlighthouse --site example.com --cookies "session_id=abc123;csrf_token=xyz789"
```
## Headers (Bearer Tokens, API Keys)
For APIs or sites expecting `Authorization` headers:
```ts
export default defineUnlighthouseConfig({
extraHeaders: {
Authorization: `Bearer ${process.env.API_TOKEN}`,
},
})
```
CLI:
```bash
unlighthouse --site api.example.com --extra-headers "Authorization:Bearer abc123"
```
## Query Params
Some staging environments use URL tokens:
```ts
export default defineUnlighthouseConfig({
defaultQueryParams: {
access_token: process.env.STAGING_TOKEN,
},
})
```
Every scanned URL will include `?access_token=...`
## localStorage (SPAs)
For React/Vue/Angular apps storing auth tokens in localStorage:
```ts
export default defineUnlighthouseConfig({
localStorage: {
auth_token: process.env.AUTH_TOKEN,
user_id: '12345',
},
})
```
Unlighthouse sets these before each page loads.
## Programmatic Login (Complex Flows)
For login forms, OAuth flows, or anything the simpler methods can't handle:
```ts
export default defineUnlighthouseConfig({
hooks: {
// the hook receives the Puppeteer page itself, not an object
async authenticate(page) {
// Navigate to login
await page.goto('https://example.com/login')
// Fill form
await page.type('input[name="email"]', 'test@example.com')
await page.type('input[name="password"]', process.env.PASSWORD)
// Submit and wait for redirect
await Promise.all([
page.click('button[type="submit"]'),
page.waitForNavigation(),
])
},
},
})
```
This runs once before scanning starts. The session persists for all pages.
## Auth Not Sticking?
If authentication isn't persisting between page scans:
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
userDataDir: './.unlighthouse-session', // Persist browser data
},
lighthouseOptions: {
disableStorageReset: true, // Don't clear storage between pages
skipAboutBlank: true,
},
})
```
## Debugging Auth Issues
Can't tell if auth is working? Watch it happen:
```ts
export default defineUnlighthouseConfig({
debug: true,
puppeteerOptions: {
headless: false, // See the browser
slowMo: 100, // Slow it down
},
puppeteerClusterOptions: {
maxConcurrency: 1, // One at a time
},
})
```
Now you can watch the browser and see exactly where auth fails.
See the [Debugging Guide](/guide/guides/debugging) for more techniques.
---
### 1.Guide Guides Chrome Dependency (`docs/1.guide/guides/chrome-dependency.md`)
---
title: "Chrome Dependency"
description: "Configure Chrome browser settings for Unlighthouse scanning, including system Chrome usage and custom installations."
keywords:
- lighthouse chrome
- puppeteer chrome
- chromium lighthouse
- chrome executable path
- lighthouse browser
navigation:
title: "Chrome Dependency"
relatedPages:
- path: /guide/guides/puppeteer
title: Puppeteer Configuration
- path: /guide/guides/common-errors
title: Common Errors
- path: /guide/guides/docker
title: Docker
---
Unlighthouse uses your system Chrome installation to keep package size minimal. When Chrome isn't available, it automatically downloads a compatible Chromium binary.
## Disabling system Chrome
You can disable the system chrome usage by modifying the `chrome.useSystem` flag.
This will make Unlighthouse download and use the latest Chrome binary instead.
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
chrome: {
useSystem: false
},
})
```
## Customizing the fallback installer
When Chrome can't be found on your system or if the `chrome.useSystem: false` flag is passed, then a fallback will be attempted.
This fallback will download a chrome binary for your system and use that path.
There are a number of options you can customize on this.
- `chrome.useDownloadFallback` - Disables the fallback installer
- `chrome.downloadFallbackVersion` - Which Chrome for Testing version to download (default: the version pinned by the installed `puppeteer-core`)
- `chrome.downloadFallbackCacheDir` - Where the binary should be saved (default `$home/.unlighthouse`)
```ts
export default defineUnlighthouseConfig({
chrome: {
useDownloadFallback: true,
downloadFallbackVersion: '153.0.8010.36',
downloadFallbackCacheDir: '/tmp/unlighthouse',
},
})
```
## Using your own chrome path
You can provide your own chrome path by setting `puppeteerOptions.executablePath`.
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
executablePath: '/usr/bin/chrome',
},
})
```
---
### 1.Guide Guides Common Errors (`docs/1.guide/guides/common-errors.md`)
---
title: "Common Errors"
description: "Troubleshoot common issues encountered when running Unlighthouse scans, including browser connection and environment problems."
keywords:
- lighthouse error
- lighthouse not working
- puppeteer error
- chrome connection refused
- wsl lighthouse
- lighthouse troubleshooting
- stop unlighthouse
- ctrl c not working git bash
navigation:
title: "Common Errors"
relatedPages:
- path: /guide/guides/debugging
title: Debugging
- path: /guide/guides/chrome-dependency
title: Chrome Dependency
- path: /guide/guides/puppeteer
title: Puppeteer Configuration
---
Solutions for frequently encountered issues when running Unlighthouse scans. Ensure you're using the latest version before troubleshooting.
::tip
For general debugging techniques, see the [Debugging Guide](/guide/guides/debugging).
::
## `connect ECONNREFUSED 127.0.0.1:`
**Example**
> Error: Unable to launch browser for worker, error message: connect ECONNREFUSED 127.0.0.1:51667
This error is thrown when Chromium is unable to launch. This happens when puppeteer is unable to connect to the browser.
This can be from a number of reasons:
- The environment is not configured correctly, likely when using Windows and WSL.
- You have a firewall or antivirus blocking Chrome or Chromium from launching or connecting to the required port.
- You are using an unsupported version of Chrome or Chromium.
**Windows and WSL Solution**
- Install Puppeteer on WSL following the [documentation](https://pptr.dev/troubleshooting#running-puppeteer-on-wsl-windows-subsystem-for-linux).
- Install Chrome in WSL following the [documentation](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps#install-google-chrome-for-linux).
**Other Environments**
- You can try disabling the system Chrome, instead using the fallback.
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
chrome: {
useSystem: false,
},
})
```
## Can't stop the scan with `Ctrl+C`
Unlighthouse keeps running after a scan so you can browse the dashboard. Press `Ctrl+C` in the terminal to stop it; this shuts down the dev server and closes Chrome.
If `Ctrl+C` does nothing, you are almost certainly running inside **Git Bash (MinTTY)** on Windows. MinTTY does not forward `Ctrl+C` to native console programs such as Node, so the process keeps running and you have to kill it from Task Manager.
**Solutions**
- Wrap the command with [winpty](https://github.com/rprichard/winpty), which ships with Git for Windows:
```bash
winpty npx unlighthouse --site example.com
```
- Or run the command from **PowerShell**, **Command Prompt**, or **Windows Terminal** instead of Git Bash, where `Ctrl+C` works as expected.
---
### 1.Guide Guides Device (`docs/1.guide/guides/device.md`)
---
title: "Unlighthouse --desktop Flag & Device Configuration"
description: "Run Unlighthouse in desktop mode with the --desktop flag: npx unlighthouse --site --desktop. Configure mobile, desktop, or custom viewports with throttling."
keywords:
- unlighthouse --desktop
- unlighthouse --desktop flag
- unlighthouse cli --desktop flag
- unlighthouse cli desktop option
- unlighthouse cli desktop flag
- unlighthouse --device desktop
- unlighthouse cli device desktop option
- lighthouse mobile
- lighthouse desktop
- lighthouse device emulation
- lighthouse viewport
- lighthouse throttling
- mobile performance testing
navigation:
title: "Device Configuration"
relatedPages:
- path: /guide/guides/lighthouse
title: Lighthouse Configuration
- path: /api-doc/config
title: Config Reference
- path: /glossary
title: Core Web Vitals Glossary
---
Run Unlighthouse in desktop mode with the `--desktop` flag:
```bash
npx unlighthouse --site https://example.com --desktop
```
This overrides the default mobile emulation and scans every page using a desktop viewport. Prefer a config file? Set `scanner.device: 'desktop'` instead.
## When to use `--desktop`
Mobile is the default because Google uses mobile-first indexing. But desktop scans still matter for:
- B2B SaaS dashboards (95%+ desktop traffic)
- Admin panels and internal tools
- Documentation sites
- Benchmarking against PageSpeed Insights desktop scores
The `--desktop` flag is equivalent to the `--device desktop` long form and takes precedence over any config file setting.
## Device Types
### Desktop Scanning
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
scanner: {
device: 'desktop',
},
})
```
### Mobile Scanning (Default)
```ts
export default defineUnlighthouseConfig({
scanner: {
device: 'mobile',
},
})
```
## Custom Dimensions
Test specific viewport sizes for responsive breakpoints:
```ts
export default defineUnlighthouseConfig({
lighthouseOptions: {
screenEmulation: {
width: 1800,
height: 1000,
},
},
})
```
## Network Throttling
Throttling simulates slower network and CPU conditions for more realistic performance testing:
```ts
export default defineUnlighthouseConfig({
scanner: {
throttle: true,
},
})
```
::note
Throttling is enabled by default for remote sites and disabled for local sites, such as `localhost`. Set `scanner.throttle` to `true` or `false` to override it.
::
---
### 1.Guide Guides Docker (`docs/1.guide/guides/docker.md`)
---
title: "Run Lighthouse in Docker"
description: "Run Unlighthouse site-wide Lighthouse scans in Docker containers. Dockerfile examples and CI/CD configuration."
keywords:
- lighthouse docker
- docker lighthouse
- lighthouse container
- puppeteer docker
- lighthouse ci docker
navigation:
title: "Docker"
relatedPages:
- path: /integrations/ci
title: CI Integration
- path: /guide/guides/puppeteer
title: Puppeteer Configuration
- path: /guide/guides/chrome-dependency
title: Chrome Dependency
---
Run Unlighthouse in Docker containers for consistent CI/CD environments. Docker requires special Puppeteer configuration due to sandboxing restrictions.
::warning
Docker support is community-maintained and experimental. Use the CI integration for best results.
::
## Unlighthouse Config
It's recommended you only use the `@unlighthouse/ci` with Docker. Hosting the client does not have known support.
You will need to remove the Chrome sandbox in a Docker environment, this will require using an `unlighthouse.config.ts` file.
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
puppeteerOptions: {
headless: true,
args: [
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-gpu',
'--ignore-certificate-errors',
],
},
})
```
If you're using the `unlighthouse` binary instead of the CI integration, then you will need to tell Unlighthouse not to use the server and close when
the reports are finished.
```ts
export default defineUnlighthouseConfig({
server: {
open: false,
},
hooks: {
'worker-finished': async () => {
process.exit(0)
},
},
})
```
## Docker File
Please see the following community repos:
- [indykoning—Unlighthouse Docker](https://github.com/indykoning/unlighthouse-docker)
---
### 1.Guide Guides Dynamic Sampling (`docs/1.guide/guides/dynamic-sampling.md`)
---
title: "Dynamic Sampling"
description: "Automatically sample similar pages to reduce scan time for sites with many similar URLs like blogs or e-commerce."
keywords:
- lighthouse sampling
- scan subset of pages
- lighthouse large site
- reduce lighthouse scan time
- lighthouse scan optimization
navigation:
title: "Dynamic Sampling"
relatedPages:
- path: /guide/guides/route-definitions
title: Route Definitions
- path: /guide/recipes/large-sites
title: Large Sites
- path: /guide/guides/url-discovery
title: URL Discovery
---
Automatically group similar pages and scan only representative samples. This significantly reduces scan time for sites with many similar URLs like blogs, e-commerce product pages, or documentation sites.
## How it works
When dynamic sampling is enabled, it will group paths into chunks based on their path tree.
For example, let's imagine we have a blog on our site and there are hundreds of blog posts. Scanning every blog post will
take a long time and may even break Unlighthouse.
The path structure is `/blog/{post}`.
Unlighthouse will turn this path structure into groups based on the `/blog` prefix. By default, it will sample
5 paths starting with this prefix.
A sample being a random selection of paths within this group.
For example if we have the posts:
- `/blog/post-a`
- `/blog/post-b`
- `/blog/post-c`
- `/blog/post-d`
- `/blog/post-e`
- `/blog/post-f`
- `/blog/post-g`
- `/blog/post-h`
- `/blog/post-i`
After sampling, we may end up with the random selection:
- `/blog/post-c`
- `/blog/post-d`
- `/blog/post-e`
- `/blog/post-h`
- `/blog/post-i`
## Usage
It is configured using the `scanner.dynamicSampling` option.
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
scanner: {
dynamicSampling: 10, // Number of samples per group (default: 8)
},
})
```
### Disable Dynamic Sampling
```ts
export default defineUnlighthouseConfig({
scanner: {
dynamicSampling: false,
},
})
```
Alternatively, you can disable it using the CLI `--disable-dynamic-sampling`.
---
### 1.Guide Guides Generating Static Reports (`docs/1.guide/guides/generating-static-reports.md`)
---
title: "Generate Lighthouse Reports"
description: "Generate static Lighthouse reports for your entire site. Export as HTML, CSV, or JSON. Deploy to Netlify, CloudFlare, or any static host."
keywords:
- lighthouse report
- lighthouse html report
- lighthouse json report
- lighthouse csv export
- static lighthouse report
- lighthouse report generation
- bulk lighthouse report
navigation:
title: "Static Reports"
relatedPages:
- path: /integrations/ci
title: CI Integration
- path: /guide/guides/config
title: Configuration
- path: /guide/recipes/client
title: UI Customization
---
Create static, shareable Lighthouse reports for your entire site. Export as interactive HTML dashboards, CSV for spreadsheet analysis, or JSON for CI/CD integration.
## Report Types
| Format | Use Case | Command |
|--------|----------|---------|
| HTML | Shareable dashboards | `--build-static` |
| JSON | CI/CD integration | `--reporter json` |
| CSV | Spreadsheet analysis | `--reporter csv` |
| LHCI | Server upload | `--reporter lighthouseServer` |
Unlike single-page Lighthouse reports, Unlighthouse aggregates results across your entire site.
::tip
Static reports are perfect for stakeholder reviews, automated deployments, and long-term performance tracking.
::
## Installation
Install the CLI globally to use `unlighthouse-ci`:
::code-group
```bash [npm]
npm install @unlighthouse/cli
```
```bash [yarn]
yarn global add @unlighthouse/cli
```
```bash [pnpm]
pnpm install @unlighthouse/cli
```
::
For complete CI features, see the [CI Integration Guide](/integrations/ci).
## HTML Reports
You can create static, self-hosted reports for your sites using the CI. This allows you to generate an always up-to-date version
of how your site is performing overall.
You can see an example of this here: .
You can generate a report like this by providing the `--build-static` flag.
```bash
unlighthouse-ci --site --build-static
```
This will generate files in your `outputPath` (`.unlighthouse` by default). Upload that whole folder to a static host; `index.html` sits at its root.
If you want to preview the static report you can run `npx sirv-cli .unlighthouse`
Note: You will need to host your site using a web server.
### CloudFlare Pages Example
You should create a CloudFlare Pages site using [Direct Upload](https://developers.cloudflare.com/pages/platform/direct-upload/).
You will use the [wrangler](https://developers.cloudflare.com/pages/platform/using-wrangler) CLI to upload the static report.
You will need to init wrangler and configure it for your requirements.
```bash
wrangler init
```
You can then run the following command to generate the static report and upload it to CloudFlare Pages.
```bash
unlighthouse-ci --site www.example.com --build-static && wrangler pages publish .unlighthouse
```
### GitHub Actions & Netlify Example
This example is for GitHub Actions and deploys a static client build to Netlify.
```yml unlighthouse.yml
name: Assertions and static report
on:
workflow_dispatch:
jobs:
demo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Dependencies
run: npm add @unlighthouse/cli
- name: Unlighthouse assertions and client
run: unlighthouse-ci --site --build-static
- name: Deploy report to Netlify
uses: nwtgck/actions-netlify@v3.0
with:
publish-dir: ./.unlighthouse
production-branch: main
production-deploy: true
github-token: ${{ secrets.GITHUB_TOKEN }}
deploy-message: New Release Deploy from GitHub Actions
enable-pull-request-comment: false
enable-commit-comment: true
overwrites-pull-request-comment: true
env:
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_DEMO_SITE_ID }}
timeout-minutes: 1
```
## CSV Reports
You can generate a CSV report by providing the `--reporter csv` or `--reporter csvExpanded` flag.
```bash
unlighthouse-ci --site --reporter csv
```
Note: This report format is experimental and may change in the future.
This will generate a report like the following (`csvExpanded` sample):
```csv
URL,Score,Performance,Accessibility,Best Practices,SEO,Largest Contentful Paint,Cumulative Layout Shift,FID,Blocking,Color Contrast,Headings,Image Alts,Link Names,Errors,Inspector Issues,Images Responsive,Image Aspect Ratio,Indexable,Tap Targets
"/",93,72,100,100,100,3211.44,0,290.36,562.29,1,1,1,1,1,1,1,1,1,1
"/blog",94,77,100,100,100,3911.7,0,205.57,260.03,1,1,1,1,1,1,1,1,1,1
"/blog/2023-april",88,51,100,100,100,4925.84,0,311.24,797.95,1,1,1,1,1,1,1,1,1,1
"/blog/2023-february",96,82,100,100,100,3207.98,0,209.96,302.01,1,1,1,1,1,1,1,1,1,1
"/blog/nuxt-3-migration-cheatsheet",85,43,97,100,100,4373.88,0,1581.52,2820.75,0,1,1,1,1,1,1,1,1,1
"/blog/vue-automatic-component-imports",93,74,97,100,100,1696.51,0,793.36,1314.27,0,1,1,1,1,1,1,1,1,1
"/blog/vue-use-head-v1",82,30,97,100,100,8053.8,0,379.59,1127.99,0,1,1,1,1,1,1,1,1,1
"/projects",92,66,100,100,100,3666.86,0,322.48,625.51,1,1,1,1,1,1,1,1,1,1
"/sponsors",92,69,100,100,100,4438.15,0,362.62,408.63,1,1,1,1,1,1,1,1,1,1
"/talks",98,90,100,100,100,864.86,0,390.93,427.94,1,1,1,1,1,1,1,1,1,1
```
## JSON Reports
You can generate a JSON report by providing the `--reporter json` or `--reporter jsonExpanded` flag.
```bash
unlighthouse-ci --site --reporter json
```
Note: This report format is experimental and may change in the future.
This will generate a report like the following (`json` sample):
```
/* Detailed source-code truncated for AI context efficiency. */
```
## LHCI Reports
You can upload your reports to a Lighthouse CI server using the `lighthouseServer` reporter.
You will need to provide the `--lhci-host` and `--lhci-build-token` flags.
```bash
unlighthouse-ci --site --reporter lighthouseServer --lhci-host --lhci-build-token
```
This will upload your reports to the Lighthouse CI server.
### Basic Auth
You can provide basic auth credentials using the `--lhci-auth` flag.
```bash
unlighthouse-ci --site --reporter lighthouseServer --lhci-host --lhci-build-token --lhci-auth :
```
---
### 1.Guide Guides Lighthouse (`docs/1.guide/guides/lighthouse.md`)
---
title: "Lighthouse Configuration"
description: "Customize Google Lighthouse audit settings, categories, and performance thresholds within Unlighthouse scans."
keywords:
- lighthouse options
- lighthouse configuration
- lighthouse categories
- customize lighthouse
- lighthouse audit settings
navigation:
title: "Lighthouse Config"
relatedPages:
- path: /guide/guides/device
title: Device Configuration
- path: /api-doc/config
title: Config Reference
- path: /glossary
title: Core Web Vitals Glossary
---
Customize audit categories, performance thresholds, and behavior through the `lighthouseOptions` configuration key. Unlighthouse passes these options directly to Google Lighthouse.
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
lighthouseOptions: {
throttlingMethod: 'devtools',
},
})
```
For complete options, see the [Lighthouse Configuration docs](https://github.com/GoogleChrome/lighthouse/blob/master/docs/configuration.md).
## Aliases
Unlighthouse aims to minimise and simplify configuration, where possible.
For this reason, a number of configurations aliases are provided for your convenience.
- [Switching device: mobile and desktop](/guide/guides/device)
- [Toggle Throttling](/guide/guides/device#network-throttling)
You can always configure lighthouse directly if you are comfortable with the configuration.
## Selecting Categories
By default, Unlighthouse will scan the categories: `'performance', 'accessibility', 'best-practices', 'seo'`.
The performance category measures [Core Web Vitals](/glossary) including [LCP](/glossary/lcp), [CLS](/glossary/cls), and [INP](/glossary/inp).
It can be useful to remove certain categories from being scanned to improve scan times. The Unlighthouse UI will adapt
to any categories you select.
**Only Performance**
```ts
export default defineUnlighthouseConfig({
lighthouseOptions: {
onlyCategories: ['performance'],
},
})
```
---
### 1.Guide Guides Puppeteer (`docs/1.guide/guides/puppeteer.md`)
---
title: "Puppeteer Launch Options"
description: "Configure Puppeteer launch options in Unlighthouse: headless mode, Chrome args, viewport settings, executable path, and navigation hooks."
keywords:
- puppeteer launch options
- puppeteer.launch options
- puppeteer args
- puppeteer headless
- puppeteer chrome flags
- lighthouse puppeteer
- puppeteer evaluateonnewdocument localstorage
- puppeteer.evaluateonnewdocument
- puppeteer set localstorage
navigation:
title: "Puppeteer"
relatedPages:
- path: /guide/guides/chrome-dependency
title: Chrome Dependency
- path: /guide/guides/authentication
title: Authentication
- path: /guide/guides/docker
title: Docker
---
Unlighthouse uses [Puppeteer](https://pptr.dev/) to control Chrome for Lighthouse audits. Configure browser behavior, navigation hooks, and Chrome flags via `puppeteerOptions`.
## All Available Options
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
// See: https://pptr.dev/api/puppeteer.launchoptions
},
})
```
Full reference: [Puppeteer LaunchOptions API](https://pptr.dev/api/puppeteer.launchoptions)
## Common Configurations
### Headless Mode
```ts
// Run with visible browser (debugging)
export default defineUnlighthouseConfig({
puppeteerOptions: {
headless: false,
},
})
```
### Custom Chrome Executable
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
executablePath: '/usr/bin/google-chrome',
},
})
```
### Chrome Arguments
Common args for CI/Docker environments:
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
args: [
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage',
'--disable-gpu',
],
},
})
```
### Viewport Settings
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
defaultViewport: {
width: 1920,
height: 1080,
},
},
})
```
### Timeout Configuration
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
timeout: 60000, // 60 seconds
},
})
```
### User Data Directory
Persist browser data between runs:
```ts
export default defineUnlighthouseConfig({
puppeteerOptions: {
userDataDir: './.puppeteer-data',
},
})
```
## Navigation Hooks
Hook into Puppeteer's page navigation for custom logic.
### Before Page Load
```ts
export default defineUnlighthouseConfig({
hooks: {
'puppeteer:before-goto': async (page) => {
// Set localStorage before navigation
await page.evaluateOnNewDocument((token) => {
localStorage.setItem('auth', token)
}, process.env.AUTH_TOKEN)
},
},
})
```
### Modify Page Content
```ts
export default defineUnlighthouseConfig({
hooks: {
'puppeteer:before-goto': async (page) => {
page.waitForNavigation().then(async () => {
// Remove elements that cause CLS
await page.evaluate(() => {
document.querySelector('.cookie-banner')?.remove()
})
})
},
},
})
```
## Troubleshooting
### Chrome not found
See [Chrome Dependency Guide](/guide/guides/chrome-dependency).
### Connection refused in Docker
Add `--no-sandbox` and `--disable-dev-shm-usage` args.
### Memory issues
Reduce concurrent workers or add `--disable-dev-shm-usage`.
---
### 1.Guide Guides Route Definitions (`docs/1.guide/guides/route-definitions.md`)
---
title: "Route Definitions"
description: "Configure route discovery and custom sampling patterns for better page organization and intelligent scanning."
keywords:
- lighthouse routes
- page discovery
- custom sampling
- route mapping
- lighthouse url mapping
navigation:
title: "Route Definitions"
relatedPages:
- path: /guide/guides/dynamic-sampling
title: Dynamic Sampling
- path: /guide/guides/url-discovery
title: URL Discovery
- path: /guide/guides/config
title: Configuration
---
Map URLs to source files for intelligent [dynamic sampling](/guide/guides/dynamic-sampling). Framework integrations discover routes automatically; CLI users may need manual configuration for optimal sampling.
## Pages directory
By default, the `pages/` dir is scanned for files with extensions `.vue` and `.md`, from the `root` directory.
If your project has a different setup you can modify the configuration.
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
root: './app',
discovery: {
pagesDir: 'routes',
fileExtensions: ['jsx', 'md'],
},
})
```
## Custom sampling
When you have URL patterns which don't use URL segments or the mapping is failing, it can be useful to map the sampling
yourself.
By using the `customSampling` option you map regex to a route definition.
In the below example we will map any URL such as `/q-search-query`, `/q-where-is-the-thing` to a single route
definition, which allows the sampling to work.
```ts
export default defineUnlighthouseConfig({
scanner: {
customSampling: {
'/q-(.*?)': {
name: 'search-query',
},
},
},
})
```
---
### 1.Guide Guides Url Discovery (`docs/1.guide/guides/url-discovery.md`)
---
title: "URL Discovery"
description: "How Unlighthouse discovers pages using sitemaps, robots.txt, and internal link crawling. Configure URL sources and filters."
keywords:
- lighthouse sitemap
- crawl website lighthouse
- lighthouse all pages
- automatic url discovery
- lighthouse find all pages
navigation:
title: "URL Discovery"
relatedPages:
- path: /guide/guides/route-definitions
title: Route Definitions
- path: /guide/recipes/large-sites
title: Large Sites
- path: /guide/guides/config
title: Configuration
---
Unlighthouse automatically finds all pages on your site using multiple discovery methods. Configure which sources to use and filter results to scan exactly what you need.
Unlighthouse discovers URLs through multiple methods:
1. Add the specified `site` from `--site` or config
2. Manually providing URLs via the `--urls` flag or `urls` on the provider.
3. `robotsTxt` - Reading robots.txt, if it exists. Provides sitemap URLs and disallowed paths.
4. `sitemap` - Reading sitemap.xml, if it exists
5. `crawler` - Inspecting internal links
6. Using provided static [route definitions](/api-doc/glossary#route-definition)
## Robots.txt
When a robots.txt is found, it will attempt to read the sitemap and disallowed paths.
### Disabling robots
You may not want to use the robots.txt in all occasions. For example if you want to scan
URLs which are disallowed.
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
scanner: {
// disable robots.txt scanning
robotsTxt: false,
},
})
```
## Sitemap.xml
By default, the sitemap config will be read from your `/robots.txt`. Otherwise, it will fall back to using `/sitemap.xml`.
Note: When a sitemap exists with over 50 paths, it will disable the crawler.
### Manual sitemap paths
You may provide an array of sitemap paths to scan.
```ts
export default defineUnlighthouseConfig({
scanner: {
sitemap: [
'/sitemap.xml',
'/sitemap2.xml',
],
},
})
```
### Disabling scan
If you know your site doesn't have a sitemap, it may make sense to disable it.
```ts
export default defineUnlighthouseConfig({
scanner: {
// disable sitemap scanning
sitemap: false,
},
})
```
## Crawler
When enabled, the crawler will inspect the HTML payload of a page and extract internal links.
These internal links will be queued up and scanned if they haven't already been scanned.
## Disable crawling
If you have many pages with many internal links, it may be a good idea to disable the crawling.
```ts
export default defineUnlighthouseConfig({
scanner: {
crawler: false,
},
})
```
## Manually Providing URLs
While not recommended for most use cases, you may provide relative URLs within your configuration file, or use the `--urls` flag.
This will disable the crawler and sitemap scanning.
Can be provided statically.
```ts
export default defineUnlighthouseConfig({
urls: [
'/about',
'/other-page',
],
})
```
Or you can return a function or promise.
```ts
export default defineUnlighthouseConfig({
urls: async () => await getUrls(),
})
```
Specify explicit relative URLs as a comma-separated list.
```bash
unlighthouse --site https://example.com --urls /about,/other-page
```
---
### 1.Guide Recipes Client (`docs/1.guide/recipes/client.md`)
---
title: "Customizing the UI"
description: "Modify Unlighthouse client interface columns and display to show custom metrics and data."
keywords:
- lighthouse dashboard
- lighthouse ui
- custom lighthouse metrics
- lighthouse report customization
- lighthouse custom columns
navigation:
title: "UI Customization"
relatedPages:
- path: /api-doc/glossary
title: Glossary
- path: /guide/guides/config
title: Configuration
- path: /guide/guides/generating-static-reports
title: Static Reports
---
Customize the Unlighthouse dashboard to display metrics relevant to your workflow. Replace default columns, add custom audit displays, and configure how results appear.
## Customizing Columns
Replace or add columns to display specific Lighthouse metrics:
### Example: Replace FCP with Server Response Time
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
hooks: {
'resolved-config': function (config) {
config.client.columns.performance[2] = {
cols: 1,
label: 'Response Time',
tooltip: 'Time for the server to respond',
sortKey: 'numericValue',
key: 'report.audits.server-response-time',
}
},
},
})
```
::tip
See the [Column API Reference](/api-doc/glossary#columns) for all available column options.
::
---
### 1.Guide Recipes Improving Accuracy (`docs/1.guide/recipes/improving-accuracy.md`)
---
title: "Improving Lighthouse Accuracy"
description: "Optimize Lighthouse scan accuracy with multiple samples and reduced concurrency for more reliable, consistent Core Web Vitals results."
keywords:
- lighthouse accuracy
- lighthouse score variability
- lighthouse consistent results
- lighthouse multiple runs
- core web vitals accuracy
- lighthouse reliable scores
navigation:
title: "Improving Accuracy"
relatedPages:
- path: /guide/guides/config
title: Configuration
- path: /guide/guides/device
title: Device Configuration
- path: /glossary
title: Core Web Vitals Glossary
---
Lighthouse scores can vary 5-10 points between runs due to network conditions, CPU load, and browser state. These techniques improve consistency for reliable [Core Web Vitals](/glossary) measurement.
## Why Scores Vary
Single Lighthouse runs can fluctuate by 5-10 points due to:
- CPU load from other browser tabs or processes
- Network latency variations
- Memory pressure
- Background service workers
For reliable performance monitoring, use multiple samples.
## Multiple Samples Per URL
Run Lighthouse multiple times and average the results for better accuracy:
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
scanner: {
samples: 3, // Run 3 scans per URL and average results
},
})
```
::tip
Use `samples: 3` for development, `samples: 5` for CI/production audits.
::
## Reduce Parallel Scans
Limit concurrent workers to reduce CPU contention and improve score consistency:
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
puppeteerClusterOptions: {
maxConcurrency: 1, // Single worker for maximum accuracy
},
})
```
## Enable Throttling
Network throttling simulates real-world conditions and reduces score variability:
```ts
export default defineUnlighthouseConfig({
scanner: {
throttle: true, // Simulate 4G network
},
})
```
## Recommended Production Config
For the most accurate results:
```ts
export default defineUnlighthouseConfig({
scanner: {
samples: 5,
throttle: true,
},
puppeteerClusterOptions: {
maxConcurrency: 1,
},
})
```
::warning
Higher accuracy increases scan time significantly. Balance accuracy needs with scan duration.
::
---
### 1.Guide Recipes Large Sites (`docs/1.guide/recipes/large-sites.md`)
---
title: "Bulk Lighthouse Testing for Large Sites"
description: "Scan large websites with thousands of pages efficiently. Configure sampling, URL filtering, and optimization strategies for bulk Lighthouse testing."
keywords:
- bulk lighthouse test
- scan entire website lighthouse
- lighthouse all pages
- site wide lighthouse
- batch lighthouse
- lighthouse thousands of pages
- enterprise lighthouse
navigation:
title: "Large Sites"
relatedPages:
- path: /guide/guides/dynamic-sampling
title: Dynamic Sampling
- path: /guide/guides/url-discovery
title: URL Discovery
- path: /guide/guides/route-definitions
title: Route Definitions
---
Scan websites with thousands of pages efficiently. Unlike single-page tools like PageSpeed Insights, Unlighthouse handles large sites with smart sampling, parallel scanning, and configurable limits.
- **Automatic discovery** - Finds all pages via sitemap and crawling
- **Smart sampling** - Tests representative pages from each template
- **Parallel scanning** - Multiple Chrome instances for speed
- **Aggregated results** - Site-wide scores and insights
Unlighthouse includes smart defaults for large sites. Understanding these helps balance completeness with performance.
## Default Large Site Configuration
These defaults optimize scanning for sites with thousands of pages:
- [ignoreI18nPages](/api-doc/config#scanner-ignorei18npages) enabled
- [maxRoutes](/api-doc/config#scanner-maxroutes) set to 200
- [skipJavascript](/api-doc/config#scanner-skipjavascript) enabled
- [samples](/api-doc/config#scanner-samples) set to 1
- [throttling](/api-doc/config#scanner-throttle) enabled, except for local sites
- [crawler](/api-doc/config#scanner-crawler) enabled
- [dynamicSampling](/api-doc/config#scanner-dynamicsampling) set to 8
For example, when scanning a blog with thousands of posts, it may be redundant to scan every single blog post, as the
DOM is very similar. Using the configuration we can select exactly how many posts should be scanned.
## Manually select URLs
You can configure Unlighthouse to use an explicit list of relative paths. This can be useful if you have a fairly complex
and large site.
See [Manually providing URLs](/guide/guides/url-discovery#manually-providing-urls) for more information.
## Provide Route Definitions (optional)
To make the most intelligent sampling decisions, Unlighthouse needs to know which page files are available. When running
using the
integration API, Unlighthouse will automatically provide this information.
Using the CLI you should follow the [providing route definitions](/guide/guides/route-definitions) guide.
Note: When no route definitions are provided it will match based on URL fragments, i.e `/blog/post-slug-3` will be
mapped to
`blog-slug`.
## Exclude URL Patterns
Paths to ignore from scanning.
For example, if your site has a documentation section, that doesn't need to be scanned.
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
scanner: {
exclude: [
'/docs/**',
],
},
})
```
## Include URL Patterns
Explicitly include paths; this will exclude any paths not listed here.
For example, if you run a blog and want to only scan your article and author pages.
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
scanner: {
include: [
'/', // the crawler starts here
'/articles/**',
'/authors/**',
],
},
})
```
## Change Dynamic Sampling Limit
By default, a URL will be matched to a specific route definition 8 times.
You can change the sample limit with:
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
scanner: {
dynamicSampling: 20, // 20 samples per page template
},
})
```
## Disabling Sampling
In cases where the route definitions aren't provided, a less-smart sampling will occur where URLs under the same parent
will be sampled.
For these instances you may want to disable the sample as follows:
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
scanner: {
dynamicSampling: false, // Disable sampling completely
},
})
```
---
### 1.Guide Recipes Spa (`docs/1.guide/recipes/spa.md`)
---
title: "Single-Page Applications"
description: "Configure Unlighthouse to scan single-page applications (SPAs) with client-side routing like React, Vue, and Angular apps."
keywords:
- lighthouse spa
- lighthouse react
- lighthouse vue
- lighthouse angular
- lighthouse client side rendering
- spa performance testing
- lighthouse csr
navigation:
title: "SPAs"
relatedPages:
- path: /guide/guides/url-discovery
title: URL Discovery
- path: /guide/guides/puppeteer
title: Puppeteer Configuration
- path: /glossary/lcp
title: LCP for SPAs
---
Scan React, Vue, Angular, and other SPAs with client-side routing. SPAs require JavaScript execution for link discovery and accurate [Core Web Vitals](/glossary) measurement.
## Enable JavaScript Execution
Allow Puppeteer to execute JavaScript before extracting page content:
```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'
export default defineUnlighthouseConfig({
scanner: {
skipJavascript: false, // Enable JS execution for SPAs
},
})
```
## Wait for Hydration
SPAs often need time to hydrate. Configure wait conditions:
```ts
export default defineUnlighthouseConfig({
scanner: {
skipJavascript: false,
},
lighthouseOptions: {
maxWaitForLoad: 45000, // Wait up to 45s for page load
},
})
```
## Provide URLs Manually
If automatic crawling misses routes, provide them explicitly:
```ts
export default defineUnlighthouseConfig({
urls: [
'/',
'/about',
'/products',
'/contact',
],
scanner: {
skipJavascript: false,
},
})
```
## SPA Performance Considerations
SPAs typically have worse [LCP](/glossary/lcp) scores because:
- Content renders after JavaScript execution
- Initial HTML is often empty or minimal
- Hydration adds to [INP](/glossary/inp) delays
Consider SSR or SSG for content-heavy pages to improve Core Web Vitals.
::note
Enabling JavaScript execution increases scan time but is necessary for accurate SPA scanning.
::
---
--- METRICS ---
- Files Extracted: 47
- Estimated Token Budget: ~43338 tokens
- Canonical Reference: https://codewiki.google/github.com/harlan-zw/unlighthouse
