How do I build a static Unlighthouse report?

`npx unlighthouse-ci --site https://example.com --build-static` writes a static report to `.unlighthouse/`. Publish that directory and the whole scan lives at one URL.

How is this different from a single Lighthouse run?

Lighthouse audits one URL. Unlighthouse crawls the site and audits every route, which is the version that answers 'which pages are slow' rather than 'is the homepage slow'. The report is correspondingly bigger and more worth publishing.

Does the interactive report work when published?

Yes — publish the whole `.unlighthouse/` directory so the assets and per-route data upload alongside the entry page. Scripts run inside a sandboxed iframe, so sorting and filtering the route table still work.

How do I show performance work is landing?

PATCH the same report id per environment on each scan. One URL with a revision per scan makes the score movement visible without anyone keeping a spreadsheet.

Can it run on a schedule?

Yes. A routine re-scans on a cron and refreshes the report, so a regression from a third-party script shows up without a deploy to trigger it.

Share an Unlighthouse report

A single Lighthouse score is a fact about one URL, and every performance conversation immediately outgrows it. The homepage is 94. The pages people actually land on from search are 61, and nobody knows that, because auditing them one at a time is nobody's job.

Unlighthouse crawls the site and audits every route. The result is the report worth arguing over — and it is a static directory on whatever machine ran the scan.

Publish it

npx unlighthouse-ci --site "$SITE" --build-static

curl -fsS -X PATCH \
  "https://commareports.com/api/v1/reports/$COMMA_REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html .unlighthouse/index.html \
        --arg title "Site audit — $SITE — $(date +%F)" \
        '{title: $title, html: $html}')"

Dragging the whole .unlighthouse/ directory into the app is usually better here — the report is a small app, and uploading the directory brings the JS, CSS and per-route data along with references rewritten to the uploaded copies. Publishing index.html alone gives you a shell with no data in it.

What the URL changes

Per-page threads. "This route is slow because of the embedded map, tracked in WEB-204" pinned to the row for that route. See commenting on HTML.
Scan-over-scan movement. Revision per scan at one URL — the only honest way to claim performance work is landing. See revisions and diffs.
Marketing and SEO can read it. No Node, no CI login.
Scheduled scans. A routine re-scans weekly, so a third-party tag that regresses LCP is caught without a deploy — see scheduled HTML reports.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total — a crawl of a few hundred routes with full Lighthouse payloads per route can pass 500 files. Narrow the crawl with --include for the published report.
Scripts run, sandboxed: allow-scripts, no allow-same-origin.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Create your first report →

Lighthouse reports — the single-page version
Sitespeed.io · Accessibility reports
Weekly digests · Publish from CI

Share an Unlighthouse report

Publish it

What the URL changes

Limits

Try it

Related