Unlighthouse: Scan Your Whole Site with Google Lighthouse

Unlighthouse is an open‑source, Node‑based command‑line interface that runs Google Lighthouse audits across every page of your website. It offers a smart sampling system, a minimal configuration model, and a clean UI that turns raw Lighthouse data into actionable insights.

What is Google Lighthouse?

Google Lighthouse is a popular auditing tool that measures web performance, accessibility, best practices, SEO, and progressive web app readiness. However, the official Lighthouse CLI is designed to audit individual URLs, not entire sites. For large applications – especially those with dozens or hundreds of pages – manually running Lighthouse on every page is impractical.

Why Unlighthouse?

Unlighthouse solves that challenge by automating Lighthouse execution across the entire domain:

• Smart sampling – By default, it crawls a subset of URLs based on a configurable strategy, dramatically reducing runtime while maintaining audit coverage.
• Zero‑config core – Just specify --site <url> and the tool takes care of crawling, running Lighthouse, and generating reports.
• Modern UI – Results are served through a lightweight web interface, giving developers instant visual feedback.
• Node & Docker ready – Runs on any machine with Node >= 20 or via Docker, making CI integration a breeze.
• MIT‑licensed – No licensing concerns, you can freely use it in commercial projects.

Quick Start

# Install via npm
npx unlighthouse --site https://your‑domain.com

# Or with PNPM
pnpm dlx unlighthouse --site https://your‑domain.com

Configuration Options

Unlighthouse supports a variety of flags and a unlighthouse.config.ts file for more advanced setups.

Sample Config

// unlighthouse.config.ts
import { defineUnlighthouseConfig } from "unlighthouse"

export default defineUnlighthouseConfig({
  site: "https://example.com",
  // Only audit pages that match these patterns
  include: ["/blog/*", "/products/*"],
  // Exclude admin pages
  exclude: ["/admin/**"],
  // Use 2 concurrency workers
  workers: 2,
  // Enable Lighthouse categories you care about
  lighthouse: {
    categories: ["performance", "accessibility", "seo"],
  },
})

Running in CI

Unlighthouse is CI‑friendly. Store the report folder in version control or publish it to a static hosting service. Here’s an example GitHub Actions workflow:

name: Site Audit
on: [push]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Node
        uses: actions/setup-node@v3
        with:
          node-version: 20
      - name: Run Audit
        run: |
          npx unlighthouse --site https://your‑site.com --output-dir ./audit
      - name: Upload Report
        uses: actions/upload-artifact@v3
        with:
          name: lighthouse-report
          path: ./audit

Advanced Features

1. Sample‑Based Auditing

Unlighthouse keeps audit times low by crawling only a fraction of pages. You can tune this with the --sample-rate flag (0‑1) or create a custom sampling strategy in a config file.

2. Lighthouse Config Tuning

You can pass a custom lighthouse.json configuration or modify the defaults via the lighthouse property in the config. Typical tweaks include disabling third‑party audits or customizing score thresholds.

3. API Integration

For dynamic sites that require authentication, Unlighthouse supports Chrome launch arguments like --cookies-file or --user-data-dir. You can also embed Unlighthouse in a Node script and programmatically trigger audits.

4. Multi‑Protocol Support

While primarily HTTP‑based, Unlighthouse can be pointed at a local development server (http://localhost:3000) or a remote staging environment. It respects robots.txt by default, but you can override it with --ignore-robots if needed.

Real‑World Use Cases

Contribution Guidelines

Unlighthouse is community‑driven. Issues, pull requests, and discussions are welcome!

• Issues – File bugs or feature requests in the GitHub issue tracker.
• Pull Requests – Follow the contribution guide in CONTRIBUTING.md. We use semantic versioning and CI‑automated linting.
• Sponsor – The project is open to sponsorship via GitHub Sponsors. Contributions help maintain releases and documentation.

Final Thoughts

Unlighthouse brings the full power of Lighthouse to entire sites without the pain of manual setup. Whether you’re a front‑end engineer, a DevOps engineer, or a site owner looking to improve performance and SEO, this tool fills a crucial gap. It’s lightweight, fast, and fully open source, making it a perfect addition to any modern web workflow.

Get started today – run npx unlighthouse --site https://your‑site.com and watch your audit data turn into real improvements.