Unlighthouse: Lighthouse Audits for Your Whole Site
Unlighthouse scans your whole site with Google Lighthouse in parallel. Here's how it differs from Lighthouse CI, and how to wire it into CI with a budget.
Quick answer
Unlighthouse is an open-source CLI that runs Google Lighthouse against every page of a site instead of just one, discovering URLs from your sitemap, robots.txt, and internal links, then auditing them in parallel and rolling everything into one dashboard. Point it at a site with npx unlighthouse --site example.com and a couple of minutes later you have performance, accessibility, SEO, and best-practices scores for the entire domain, not just whichever page you remembered to check by hand.
That’s the actual value: Lighthouse itself is fine at telling you about one page. It has never been a good tool for telling you about your site.
Why auditing one page at a time stops working
Running Lighthouse against your homepage and calling it done is a habit almost everyone falls into, mostly because running it against every page manually is tedious enough that nobody does it. The problem is that performance and accessibility issues are rarely evenly distributed. A template used by five pages might be fine. The same template used by five hundred product or blog pages, with one slow embedded widget or one unoptimized hero image, can be quietly dragging down search visibility and Core Web Vitals across the whole site while your homepage (the one page anyone actually checked) scores perfectly well.
Spot-checking a handful of pages gives you false confidence. You end up finding out about a site-wide regression from a ranking drop or a support ticket instead of from a report you already had.
How Unlighthouse actually audits a whole site
Unlighthouse discovers URLs the same way a search engine would: it reads your sitemap.xml and robots.txt, and crawls internal links it finds along the way. If your site already generates a proper sitemap (this one does, generated straight from the Astro content collections), Unlighthouse doesn’t need any extra configuration to find every post, portfolio page, and category listing.
Once it has a URL list, it runs Lighthouse across them with parallel worker threads instead of one browser tab at a time, which is what actually makes scanning hundreds of pages practical instead of an overnight job. For sites with a large number of similar, dynamically generated pages, --maxRoutes lets you sample a representative subset instead of auditing every single one. That’s worth knowing about, because it means a full run isn’t always literally every URL unless you configure it to be.
The results land in a Vite-powered dashboard you can sort, filter, and re-scan from, rather than a pile of individual JSON reports you have to compare by hand. That dashboard view is where the tool earns its keep: patterns that are invisible page by page (a shared component tanking Cumulative Layout Shift everywhere it’s used, or a missing canonical tag repeated across dozens of URLs) become obvious the moment you can see every page’s score in one place.
Unlighthouse and Lighthouse CI solve different problems
These two get confused because they share “Lighthouse” in the name and both fit into CI, but they’re not competing for the same job.
Lighthouse CI (@lhci/cli) is Google’s own tool for tracking one or a few key pages over time, comparing each commit’s scores against a baseline, and failing a pull request when a specific page regresses. It’s precise and historical, and it’s the right tool when you already know which pages matter most and want tight, per-PR gating on them.
Unlighthouse is the wide-angle view: it doesn’t care which pages matter most going in, because it audits all of them and lets you find out. Use Unlighthouse to catch the regression you didn’t know to look for, and Lighthouse CI to make sure the page you already know is business-critical never quietly gets worse. Running both isn’t redundant: they’re answering different questions.
Wiring a performance budget into CI
unlighthouse-ci runs the same site-wide scan non-interactively and can fail the build against a budget instead of just producing a report nobody reads:
- name: Install Unlighthouse
run: npm install -g @unlighthouse/cli puppeteer
- name: Site-wide performance budget
run: unlighthouse-ci --site https://example.com --budget 75 --build-staticThe same budget can live in a config file instead of a flag, which is easier to keep in version control alongside the rest of your CI setup:
export default {
site: "https://example.com",
ci: {
budget: {
performance: 80,
accessibility: 90
}
}
};Unlighthouse also ships official Docker support, so if you’re already running your build inside a container the way I described when I Dockerized this site with Bun, adding a site-wide audit job to that same pipeline is a small, natural addition rather than a new tool to onboard from scratch.
Running it on a schedule instead of on every push
A full site-wide scan of a large site takes real minutes, not seconds, so gating every single push on it usually isn’t worth the CI time. A nightly or weekly scheduled run (using workflow_dispatch plus a schedule trigger) catches drift without slowing down every commit. If you’re setting that scheduling up in GitHub Actions or a Kubernetes CronJob, the timezone and DST details are exactly the kind of thing I covered in cron expressions for DevOps, so it’s worth a look before you assume a 0 2 * * * schedule means what you think it means everywhere it runs.
What a site-wide report tells you that a single audit can’t
- Shared-component regressions. A layout, font-loading strategy, or image component used across templates shows up as a pattern across dozens of scores at once, not as one confusing outlier.
- SEO issues that are invisible per-page. Duplicate titles, missing canonicals, and broken hreflang tags are much easier to spot as a list across every URL than by opening each page’s
<head>individually. - Accessibility contrast problems at scale. Unlighthouse’s accessibility audit includes contrast visualization, which is far more useful when you can see it repeat across every page using a particular color combination than when you’re checking one page and hoping it’s representative.
- Where the outliers actually are. Average scores hide bad pages. A dashboard you can sort by score does not.
Framework integration and where it came from
Unlighthouse has first-class integration with Nuxt, which makes sense given its origins in that ecosystem. If you’re running Nuxt 4 rather than Astro, the setup is closer to a module install than a standalone CLI invocation. For anything else, including a static Astro build like this site, it works the same generic way: point it at a URL, let it crawl the sitemap, and it doesn’t need to know what generated the HTML in the first place.
Honest limitations
- Headless Chrome is not free. Running dozens or hundreds of parallel Lighthouse audits needs real CPU and memory. On a constrained CI runner, a full site scan can be slow or flaky in a way a single-page Lighthouse run never is.
- Authenticated routes need extra setup. Pages behind a login aren’t audited meaningfully out of the box: you’ll need to configure cookies or headers the same way you would for any headless-Chrome-based crawler.
- Sampling means “representative,” not always “complete.” With
--maxRoutesor default sampling on large sets of dynamically generated pages, you’re seeing a subset, not literally every URL. That’s usually the right trade-off for speed, but don’t assume 100% coverage unless you’ve configured it that way. - A good average can still hide one broken page. Site-wide scores are for finding patterns. Anything genuinely business-critical (a checkout flow, a signup page) is still worth auditing individually, not just trusting the aggregate.
FAQ
Is Unlighthouse free to use?
Yes. It’s MIT-licensed and open source, with no account or paid tier required for the CLI or CI usage described here.
Does Unlighthouse replace Lighthouse CI?
No. Unlighthouse audits your whole site to surface patterns and regressions you didn’t know to look for; Lighthouse CI tracks specific pages over time and gates pull requests against a baseline. Most setups benefit from having both rather than choosing one.
Can Unlighthouse audit pages behind a login?
It can, but not with zero configuration. You’ll need to provide authentication details such as cookies or headers, the same as with any other headless-Chrome-based crawling tool.
Does Unlighthouse work with Astro or only Nuxt?
It works with any site once it’s reachable over HTTP: Nuxt has the deepest first-class integration since that’s where the project originates, but a static Astro build, a WordPress site, or anything else works through the same generic sitemap-and-crawl discovery.
Final thought
The reason this is worth setting up isn’t that Unlighthouse finds problems Lighthouse itself can’t detect: it’s that it finds them on the pages nobody remembered to check. Point it at your sitemap once, look at what comes back, and you’ll probably learn more about your site’s actual performance in ten minutes than a year of occasionally re-running Lighthouse on the homepage ever told you.
