Lighthouse review: what it is, tutorial and setup

Lighthouse drives Chrome through Puppeteer and the Chrome DevTools Protocol. Gatherers collect artifacts while the page loads: a performance trace, a log of protocol events including every network request, and page data such as the accessibility tree. Audits then evaluate those artifacts, each producing a score, and categories weight selected audits into the scores shown at the top of the report. Everything is assembled into the Lighthouse Result object, the JSON from which the HTML report is rendered. Because audits work from recorded artifacts, the same run can be re-scored and inspected later, and custom audits can be added through configuration.

Unless told otherwise, Lighthouse emulates a mobile device and applies simulated throttling. It loads the page unthrottled, then models how the load would have unfolded on a slow 4G connection, defined as 150 ms latency with 1.6 Mbps down and 750 Kbps up. The Lighthouse docs describe this as fast and deterministic but subject to edge cases, and recommend packet-level throttling for deep investigation. It is also why the original trace in DevTools does not match the reported metrics, and why a desktop run, with the desktop preset, produces very different numbers from the default mobile run.

The performance score is a weighted average of metric scores only: Total Blocking Time 30%, Largest Contentful Paint 25%, Cumulative Layout Shift 25%, First Contentful Paint 10% and Speed Index 10%. Interaction to Next Paint appears with zero weight, since a page load contains no real interaction. Each metric’s raw value is mapped to a score using curves derived from real-world HTTP Archive data, and 90 or above is rated good. Insights and diagnostics suggest improvements but do not count towards the score, which is why fixing a flagged insight sometimes leaves the number unchanged.

Since version 10, Lighthouse can audit more than a cold page load. Navigation mode is the classic run, and the only one that produces a performance score. Timespan mode records an arbitrary period with interactions, measuring layout shifts and blocking time across, for example, a single-page application transition, but gives no overall score. Snapshot mode audits the page as it stands, so accessibility and best practices can be checked in an open menu or a multi-step form. A user flow strings these together through the Node API with Puppeteer, producing one report for a whole journey.

The default categories are now performance, accessibility, best practices, SEO and, since 13.3 in May 2026, agentic browsing, which checks things such as llms.txt and WebMCP integration and is described in the code as still under development. The progressive web app category was removed in Lighthouse 12. The accessibility category runs a subset of axe-core rules, with the current release depending on axe-core 4.13 or a later 4.x, and weights them into a score. Lighthouse 13, released in October 2025, removed many performance audits in favour of insights shared with the DevTools Performance panel, and requires Node.js 22.19 or later.

Lighthouse CI’s autorun command builds on sensible defaults: it finds a static build directory or starts your server, runs Lighthouse three times per URL, applies assertions and uploads results. The official guide installs the CLI globally in the workflow. Start with collection and upload only, then add assertions once the team understands its baseline. Note that temporary public storage makes reports reachable by anyone with the link; use a self-hosted LHCI server or uploads as build artifacts for anything confidential. Remember also that @lhci/cli 0.15.1, the current release, bundles Lighthouse 12.6.1, so CI results can differ from DevTools running Lighthouse 13.

Assertions fail builds, so they must survive normal variance. Raise numberOfRuns to five for performance-sensitive pages and use the median-run aggregation, which picks the most representative run, rather than the default optimistic method, which takes the best value. Assert on metric values with maxNumericValue for the two or three metrics you actually care about, rather than on the whole performance score. Accessibility can be asserted strictly because it does not vary between runs. Begin with warn, watch a few weeks of results, then promote to error.

Most important pages sit behind a login, and the cold-load audit of a public URL misses them. User flows solve this with the Node API: Puppeteer logs in, then the flow records a navigation to the dashboard, a timespan around an interaction such as filtering a list, and a snapshot of an open dialog. The result is one report covering each step. Keep flows short and deterministic, since every step inherits the variance of a lab run, and use them for regression tracking of specific journeys rather than as a substitute for field data.

A lab run answers whether this build, on this simulated device, regressed. It does not answer how fast the site is for users. PageSpeed Insights shows both for public URLs: Lighthouse lab data, and Chrome UX Report field data collected from real Chrome users over the previous 28 days for First Contentful Paint, Largest Contentful Paint, Interaction to Next Paint and Cumulative Layout Shift. When they disagree, field data is the truth about users, and the lab is the tool for finding and checking fixes. Interaction to Next Paint in particular is a field metric; a page load contains no real interaction, which is why its lab weight is zero.

Anything that reads Lighthouse JSON is coupled to audit IDs, and majors change them. Lighthouse 13 removed audits that insights replaced, for example layout-shifts became cls-culprits-insight and dom-size became dom-size-insight, while redirects, server-response-time and uses-text-compression folded into document-latency-insight. Some audits went with no replacement, including first-meaningful-paint, font-size, offscreen-images, uses-rel-preload and third-party-facades. Search dashboards, assertion files and budgets for these IDs before upgrading, pin the Lighthouse version in CI so upgrades are deliberate, and keep Node.js at 22.19 or later. Performance scoring itself did not change in 13, so score trends remain comparable.