Lighthouse CI

Visit Website

Introduction

Lighthouse CI is a suite of tools from the Google Chrome team that makes it easy to run Lighthouse continuously, save the results, retrieve them and assert against them. The repository GoogleChrome/lighthouse-ci is licensed Apache-2.0 and was updated in November 2026.

Where Lighthouse on its own gives you a one-off report for a page, Lighthouse CI turns the same audits into a gate. You run it on every commit or pull request, compare scores and metrics with a baseline, and fail the build when a page gets slower, heavier or less accessible than your budget allows.

The project has three parts: a CLI (lhci) that collects and asserts, an optional server that stores history and shows diffs between builds, and ready-made recipes for CI providers. The README’s getting-started path uses a GitHub Actions workflow.

In the quality loop, Lighthouse CI sits at the release gate. Unit and end-to-end tests tell you a page works; Lighthouse CI tells you it still loads quickly, stays accessible to automated checks and keeps basic SEO hygiene. Because it can run against a local static build as well as a deployed preview URL, it fits both static-site pipelines and teams that deploy a preview per pull request.

Features

1. Collect: lhci collect runs Lighthouse several times per URL against a local build or a deployed preview, which reduces the noise of a single run.
2. Assert: lhci assert checks results against assertions or presets, such as minimum category scores, metric thresholds and resource budgets, and exits non-zero on failure.
3. Upload: lhci upload sends reports to a Lighthouse CI server, temporary public storage, or the file system.
4. Server and diff UI: The optional LHCI server keeps history per branch and shows a visual diff of audits between two builds.
5. Budgets: Performance budgets for timing metrics and resource sizes can be expressed in config.
6. Category coverage: Because it runs Lighthouse, the same pipeline covers performance, accessibility, best practices and SEO audits.
7. CI recipes: Documentation covers GitHub Actions and other CI providers, plus a GitHub status check integration.
8. Configurable: A lighthouserc file holds URLs, number of runs, assertions and upload targets.

Pros

1. Free and official: Apache-2.0 and maintained under the GoogleChrome organisation.
2. Turns audits into gates: Regressions fail the build instead of being noticed weeks later.
3. Several checks in one: Performance, accessibility and SEO in the same job.
4. History and diffs: The server makes it easy to see exactly which audit changed.
5. Widely used: About 7,100 GitHub stars at review time.

Cons

1. Lab data only: Lighthouse runs in a controlled lab; it does not replace real-user monitoring.
2. Run-to-run variance: Scores vary with machine load; use multiple runs and sensible thresholds.
3. Server is self-hosted: History requires running and maintaining the LHCI server and its database.
4. Page-level: It checks the URLs you list; it does not crawl a whole site (see Unlighthouse for that).
5. Accessibility coverage is partial: Automated audits find only some accessibility issues; manual review is still needed.

Usage and Links (Example)

The README’s GitHub Actions example installs and runs the CLI after your build:

- run: npm install && npm run build
- run: npm install -g @lhci/cli
- run: lhci autorun

lhci autorun collects, asserts and uploads using your lighthouserc configuration. Start with a preset and a few key URLs, then tighten assertions as the baseline stabilises.

A typical lighthouserc.json keeps the setup in one place:

{
  "ci": {
    "collect": { "staticDistDir": "./dist", "numberOfRuns": 3 },
    "assert": { "preset": "lighthouse:recommended" },
    "upload": { "target": "temporary-public-storage" }
  }
}

Practical tips:

1. Start with warnings instead of errors so the team can see the baseline before builds start failing.
2. Assert on the metrics that matter to users (for example Largest Contentful Paint and Total Blocking Time) and on page weight budgets.
3. Pin the Chrome version in CI so score changes come from your code, not the browser.
4. Use the LHCI server, or keep the uploaded reports, so reviewers can open the full Lighthouse report from the pull request.

Resources:

• GitHub repository
• Getting started guide

Pricing

Lighthouse CI is free and open source under Apache-2.0. Hosting the optional server is your own infrastructure cost.

Recommended for?

1. Frontend teams who want performance and accessibility budgets enforced on every pull request.
2. Teams already using Lighthouse manually and wanting history and automation.
3. Agencies tracking many sites with consistent audits.
4. Not a fit as your only performance signal; pair it with real-user monitoring.

Conclusion

Lighthouse CI is the standard way to turn Lighthouse audits into a CI gate, with assertions, budgets and an optional history server.

Use several runs per URL, keep thresholds realistic, and treat it as lab evidence that complements production monitoring.