---
title: "Bulk lighthouse testing & --maxRoutes config"
description: "Run Lighthouse on your entire site with Unlighthouse. Limit pages with --maxRoutes, filter by URL pattern, and automate bulk audits."
canonical_url: "https://unlighthouse.dev/learn-lighthouse/bulk-lighthouse-testing"
last_updated: "2025-01-12"
---

## `--maxRoutes` CLI flag: default 200, override with one command

Use `--maxRoutes` to raise the per-scan page limit (default is 200):

```bash
npx unlighthouse --site https://example.com --max-routes 2000
```

The flag accepts any positive integer. Pass `-1` to disable the limit and scan every URL Unlighthouse discovers. This is the fix if your bulk scan is stopping at 200 pages.

## Run Lighthouse on every page, not just the homepage

Standard Lighthouse tools test one page at a time. But your site has hundreds, maybe thousands, of pages, and the [2024 Web Almanac](https://almanac.httparchive.org/en/2024/performance) added secondary page analysis because **homepage performance is not representative of the entire site**.

**Your homepage might score 100.** What about:

- Product pages with heavy images?
- Blog posts with embedded videos?
- Category pages with infinite scroll?
- User-generated content pages?

Each page type has different performance characteristics.

## The solution: Unlighthouse

Unlighthouse crawls your site and runs Lighthouse on every page automatically.

```bash
npx unlighthouse --site https://your-site.com
```

## How it works

1. **Crawl**: Discovers all pages from your sitemap and internal links
2. **Audit**: Runs Lighthouse on each page in parallel
3. **Report**: Interactive report sorted by worst scores

## Installation

No installation required. Use npx:

```bash
npx unlighthouse --site https://your-site.com
```

Or install globally:

```bash
npm install -g unlighthouse
unlighthouse --site https://your-site.com
```

## Configuration

Create `unlighthouse.config.ts`:

```ts
export default {
  site: 'https://your-site.com',
  scanner: {
    // Crawl settings
    maxRoutes: 200,
    samples: 1,
  },
  lighthouse: {
    // Lighthouse settings
    throttling: {
      cpuSlowdownMultiplier: 4,
    },
  },
}
```

## Common options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Default
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --site
      </code>
    </td>
    
    <td>
      URL to scan
    </td>
    
    <td>
      Required
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --urls
      </code>
    </td>
    
    <td>
      Specific URLs to test
    </td>
    
    <td>
      All discovered
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --samples
      </code>
    </td>
    
    <td>
      Runs per URL
    </td>
    
    <td>
      1
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --throttle
      </code>
    </td>
    
    <td>
      Simulate slow connection
    </td>
    
    <td>
      true
    </td>
  </tr>
</tbody>
</table>

## Filtering pages

Test specific sections:

```bash
npx unlighthouse --site https://your-site.com --urls "/blog/**"

npx unlighthouse --site https://your-site.com --exclude "/admin/**"
```

## Reading results

The report shows:

- **Score distribution**: How many pages are good/needs work/poor
- **Worst pages**: Sorted by score, fix these first
- **Issue breakdown**: Common problems across your site

## Understanding lab vs field data

Google [uses field data (CrUX) for search ranking](https://developers.google.com/search/docs/appearance/core-web-vitals), not lab scores from Lighthouse.

<table>
<thead>
  <tr>
    <th>
      Aspect
    </th>
    
    <th>
      Lab Data (Lighthouse)
    </th>
    
    <th>
      Field Data (CrUX)
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Source
    </td>
    
    <td>
      Simulated tests
    </td>
    
    <td>
      Real user visits
    </td>
  </tr>
  
  <tr>
    <td>
      Used for ranking
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Yes
    </td>
  </tr>
  
  <tr>
    <td>
      Best for
    </td>
    
    <td>
      Debugging issues
    </td>
    
    <td>
      Measuring actual UX
    </td>
  </tr>
  
  <tr>
    <td>
      Update frequency
    </td>
    
    <td>
      Immediate
    </td>
    
    <td>
      <a href="https://developer.chrome.com/docs/crux/methodology" rel="nofollow">
        28-day rolling average
      </a>
    </td>
  </tr>
</tbody>
</table>

Lab testing with Unlighthouse helps you **find and fix issues**. Monitor field data to verify improvements reached real users.

## Lighthouse scoring method

[Lighthouse performance scoring](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring) weights metrics differently:

<table>
<thead>
  <tr>
    <th>
      Metric
    </th>
    
    <th>
      Weight
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Total Blocking Time (TBT)
    </td>
    
    <td>
      30%
    </td>
  </tr>
  
  <tr>
    <td>
      Largest Contentful Paint (LCP)
    </td>
    
    <td>
      25%
    </td>
  </tr>
  
  <tr>
    <td>
      Cumulative Layout Shift (CLS)
    </td>
    
    <td>
      25%
    </td>
  </tr>
  
  <tr>
    <td>
      First Contentful Paint (FCP)
    </td>
    
    <td>
      10%
    </td>
  </tr>
  
  <tr>
    <td>
      Speed Index
    </td>
    
    <td>
      10%
    </td>
  </tr>
</tbody>
</table>

Scores are derived from [real website performance data on HTTP Archive](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring):

- 0-49: Poor (red)
- 50-89: Needs Improvement (orange)
- 90-100: Good (green)

## Reducing score variability

Lighthouse scores vary between runs. Follow [Google's guidance](https://developers.google.com/web/tools/lighthouse/variability):

- **Run multiple times**: The median of 5 runs is twice as stable as 1 run
- **Use consistent hardware**: Don't run concurrent tests on the same machine
- **Isolate from third-parties**: External scripts add variance
- **Scale horizontally**: Run on multiple smaller instances rather than one large one

Unlighthouse defaults to running multiple samples and averaging for stable results.

## CI/CD integration

Run on every deploy to catch regressions:

```yaml
name: Lighthouse Audit
on: [push]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Unlighthouse
        run: npx unlighthouse-ci --site ${{ env.SITE_URL }}
```

Set performance budgets to fail builds when scores drop:

```ts
// unlighthouse.config.ts
const config2 = {
  site: 'https://your-site.com',
  ci: {
    budget: {
      performance: 80,
      accessibility: 90,
    },
  },
}
```

For CI/CD automation with performance budgets, see the [Lighthouse CI guide](/learn-lighthouse/lighthouse-ci) or platform-specific guides for [GitHub Actions](/learn-lighthouse/lighthouse-ci/github-actions) and [GitLab CI](/learn-lighthouse/lighthouse-ci/gitlab-ci).

## Alternatives comparison

How Unlighthouse compares to other tools:

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Bulk Testing
    </th>
    
    <th>
      Pricing
    </th>
    
    <th>
      Notes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Unlighthouse
      </strong>
    </td>
    
    <td>
      Unlimited pages
    </td>
    
    <td>
      Free (CLI)
    </td>
    
    <td>
      Open source, self-hosted
    </td>
  </tr>
  
  <tr>
    <td>
      PageSpeed Insights
    </td>
    
    <td>
      1 page/request
    </td>
    
    <td>
      Free
    </td>
    
    <td>
      <a href="https://developers.google.com/speed/docs/insights/v5/get-started" rel="nofollow">
        25,000 requests/day API limit
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      DebugBear
    </td>
    
    <td>
      10,000/mo
    </td>
    
    <td>
      $99/mo
    </td>
    
    <td>
      Managed service
    </td>
  </tr>
  
  <tr>
    <td>
      Calibre
    </td>
    
    <td>
      5 sites
    </td>
    
    <td>
      $150/mo
    </td>
    
    <td>
      Managed service
    </td>
  </tr>
  
  <tr>
    <td>
      SpeedCurve
    </td>
    
    <td>
      Varies
    </td>
    
    <td>
      $20-500/mo
    </td>
    
    <td>
      RUM + synthetic
    </td>
  </tr>
</tbody>
</table>

## Current web performance stats

Context for your scores from [HTTP Archive 2024](https://almanac.httparchive.org/en/2024/performance):

<table>
<thead>
  <tr>
    <th>
      Metric
    </th>
    
    <th>
      Mobile Pass Rate
    </th>
    
    <th>
      Desktop Pass Rate
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Core Web Vitals (all 3)
    </td>
    
    <td>
      48%
    </td>
    
    <td>
      54%
    </td>
  </tr>
  
  <tr>
    <td>
      LCP
    </td>
    
    <td>
      59%
    </td>
    
    <td>
      72%
    </td>
  </tr>
  
  <tr>
    <td>
      CLS
    </td>
    
    <td>
      79%
    </td>
    
    <td>
      72%
    </td>
  </tr>
  
  <tr>
    <td>
      INP
    </td>
    
    <td>
      74%
    </td>
    
    <td>
      97%
    </td>
  </tr>
</tbody>
</table>

If you're beating these numbers, you're ahead of most of the web.

## Best practices

1. **Test representative pages**: Don't just test the homepage
2. **Run multiple samples**: Average results for stability
3. **Test on realistic hardware**: Use CPU throttling to simulate mobile
4. **Monitor trends**: One-time audits aren't enough
5. **Fix worst pages first**: Greatest impact for least effort
6. **Validate with field data**: Lab scores don't affect ranking

## Next steps

1. Run your first scan: `npx unlighthouse --site https://your-site.com`
2. Fix the worst pages first
3. [Set up CI/CD](/learn-lighthouse/lighthouse-ci/github-actions) to catch regressions