unlighthouse: running Google Lighthouse across a whole site, not one URL at a time

The single-URL problem unlighthouse targets

Google Lighthouse audits one page. A site has hundreds. The README states the project's purpose plainly: it scans your entire site using Google Lighthouse, with a modern UI, minimal config and smart sampling. That sentence is the whole pitch, and it also defines the audience.

The tool is for people who already accept Lighthouse as their measurement, and who need it applied at site scale: a developer checking a redesign before release, a technical SEO person looking for the pages that score worst, or a CI job that should fail when a section of the site regresses. It is not a monitoring service and it is not a crawler that discovers content for you in a search-engine sense. It is a runner with a report attached.

Because it is distributed as an npm package, the entry cost is low: Node is the only prerequisite the README names, at version 22.18.0 or newer. That version floor is worth reading twice, since it rules out older LTS installs that many build images still carry.

How unlighthouse crawls and scores a site

The repository is a pnpm monorepo. The top-level package.json is private and named @unlighthouse/monorepo, and the build script filters on ./packages/**, so the published code lives under packages/ rather than at the root. The CLI entry the repository scripts point at is packages/cli/dist/cli.mjs, and a second entry, packages/cli/dist/ci.mjs, is what the CI script uses. A crux-api directory sits at the top level alongside docs/ and test/, which suggests the CrUX field-data integration is a separate package rather than something bolted into the CLI.

Puppeteer is a devDependency of the monorepo and is listed among the topics, which fits the mechanism you would expect: a headless browser loads each discovered URL and Lighthouse runs against that page. The sampling is the part the README calls smart. Rather than treating every URL as equally worth a full audit, unlighthouse samples the crawl, which is the only reason a scan of a large site finishes in a useful amount of time. The README does not spell out the sampling algorithm, so treat the exact selection rules as undocumented and check them against your own site before you rely on a score being representative.

Reports are written to a directory the README calls outputDir and names as .unlighthouse. The README recommends gitignoring it, which tells you the output is generated artifacts, not source you should commit.

Install unlighthouse and run your first scan

The README's Quick Setup is a single command with no install step. Replace the placeholder with your own host. The README gives this example form:

npx unlighthouse --site <your-site>

pnpm users get the equivalent invocation from the README:

pnpm dlx unlighthouse --site <your-site>

After the run, look for the .unlighthouse directory in your working directory: that is where the README says reports are saved, and it is what you add to version control exclusions. The README shows the entry on its own line:

.unlighthouse

If the scan fails or the numbers look wrong, the README's stated first step is to re-run with debugging on, using its own example host:

npx unlighthouse --site unlighthouse.dev --debug

That is the whole documented path. Everything else, including integration instructions, guides, API and config spec, the README points to the docs site at unlighthouse.dev rather than reproducing in the repository. If you need a config file, a CI recipe or a framework integration, the README is not the place to find it.

Where unlighthouse stops being the right tool

The README does not document rollback, and it does not describe how to resume or clean up a partial scan. That silence matters if you plan to run this in a pipeline: you will be designing your own recovery behaviour rather than following a documented one.

The heavier constraint is the browser. Lighthouse under Puppeteer needs a Chrome-compatible binary and the memory to run it. On a small CI runner, or in a container image that does not ship a browser, you will spend more time on the environment than on the audit. The README's requirements section names Node 22.18.0 and nothing else, so browser provisioning is on you.

Sampling is the second trade-off. It is what makes a large scan feasible, and it is also why a clean report is not proof that every page is clean. If your goal is a guaranteed pass on a fixed list of URLs, a script that loops Lighthouse over that list gives you the determinism unlighthouse deliberately trades away. And if you only ever check one page, unlighthouse adds a crawl and a report server around a job the Lighthouse CLI already does.

unlighthouse against running Lighthouse per URL yourself

The honest alternative is the Lighthouse CLI in a shell loop, or a hosted auditing service. The difference is not accuracy, since unlighthouse runs Lighthouse underneath; it is what surrounds the run.

A loop gives you exact control: you choose the URL list, you choose the parallelism, you decide what happens on failure. You also own the crawl, the report storage, the aggregation and the UI. unlighthouse packages all four, and its sampling means you do not have to enumerate URLs in advance. The cost of that convenience is the undocumented parts: the sampling rules and the report format are not specified in the README, so tooling that parses .unlighthouse output is building on an interface the project has not committed to in writing.

A hosted service differs in the other direction. It keeps history and alerting for you, and it usually runs from its own network rather than yours. unlighthouse runs locally, which is why the README can offer a --debug flag as the first troubleshooting step: the browser, the crawl and the report are all on your machine, and you can inspect them. If you need a run to be reproducible on a machine you control, that locality is the argument for unlighthouse over a dashboard.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-22, the same day as the v0.18.1 release. The two releases before it, v0.18.0 and v0.17.10, landed on 2026-06-29 and 2026-06-08. That is a project with recent activity and a version line still below 1.0, so minor releases can carry breaking changes and the docs site, not the README, is where the current config spec lives.

Upgrade cost is mostly the Node floor plus whatever the CLI surface changes between minors. Because the package is consumed through npx or pnpm dlx, an unpinned invocation picks up whatever is latest, which is convenient for a one-off scan and risky in CI. Pin the version in any pipeline you care about.

The licence is MIT, stated in the README and in the repository's LICENSE.md, and the monorepo package.json carries "license": "MIT". MIT permits commercial use and modification with the copyright notice retained; that is a summary of the licence text, not legal advice, and you should read LICENSE.md yourself. One practical note: the README's sponsor section links to the author's Sponsor Program, and the project is maintained by a single author, so support expectations should match that.

Editorial conclusion

Adopt unlighthouse when you need Lighthouse numbers for many URLs in one run and you want the report on your own machine or in CI rather than in a hosted dashboard. Do not adopt it if you cannot run Puppeteer in your environment, if you only ever audit one page, or if you need a documented rollback procedure, since the README does not describe one. Before committing, verify that Node is at least 22.18.0 and that .unlighthouse is in your .gitignore, then run a scan with --debug on a staging host so the crawl and the report paths are confirmed against your own site.

Frequently asked questions

Official sources

1. harlan-zw/unlighthouse on GitHub
2. License: MIT
3. Project website
4. README
5. Releases