Skip to content

Concept in Performance

Lighthouse after the PWA category

Published Updated

Lighthouse is an open-source automated tool that runs audits against a supplied web page and produces a report. Its documented workflows include Chrome DevTools, the command line, a Node module, PageSpeed Insights, and Lighthouse CI.

Chrome 126 bundled Lighthouse 12.0.0 and its release notes identify removal of the PWA category. Lighthouse still audits web-page quality, but a report from that version does not provide the former PWA category.

Give Lighthouse a URL and it runs a series of audits against the page. Each failed audit links to a reference that explains the audit and a possible fix (Introduction to Lighthouse, Chrome for Developers). The same overview names audits for performance, accessibility, SEO, and other aspects of page quality. It does not define a single PWA-installation score after the category removal.

Chrome DevTools provides a Lighthouse workflow inside Chrome. The command-line workflow installs the lighthouse package globally or invokes its executable, then supplies a URL and options. The Node workflow exposes Lighthouse to JavaScript. PageSpeed Insights is another documented way to run Lighthouse, while Lighthouse CI is designed to prevent regressions.

For a Lighthouse 12 pipeline, the versioned CLI documentation is the contract for the flags passed by automation. It lists --only-categories with the available accessibility, best-practices, performance, and seo values; --chrome-flags for flags forwarded to Chrome; and --output plus --output-path for choosing JSON and its destination (Lighthouse v12.0.0 CLI options, GoogleChrome/lighthouse). Pinning this documentation to v12.0.0 matters because it describes the same major release as the examples and the Chrome 126 removal notice.

The matching result type documents the other half of that contract. A full result has a string lighthouseVersion and a categories record keyed by category identifier. Each category has a score whose type is number | null, so consumers should not assume that every present category always supplies a numeric value (Lighthouse v12.0.0 result type, GoogleChrome/lighthouse). Checking the artifact and requested category keys before using their scores produces a more specific CI failure than letting an unchecked property access fail later.

The Chrome 126 DevTools release notes say that DevTools runs Lighthouse 12.0.0 and list PWA category removal among that update’s changes (What’s new in DevTools, Chrome 126, Chrome for Developers). The Lighthouse removal issue assigns the work to the v12.0 milestone and tracks removal of the category from the report, including the JSON result (Remove PWA Category, GoogleChrome/lighthouse).

Chrome’s installability documentation gives useful context without turning the old audits into browser requirements. It says Chromium install criteria included a manifest with fields such as a name and icon, plus a service worker with a fetch handler. Chrome removed the fetch-handler requirement for installation from the menu in version 108 on mobile and 112 on desktop. The same document says the install-prompt algorithm still required a fetch handler when that change was described (Revisiting Chrome’s installability criteria, Chrome for Developers).

Treat Lighthouse output and browser install UI as separate evidence. A Lighthouse report describes the audits that were run. Browser install behavior comes from the browser’s own criteria and interfaces. The beforeinstallprompt event can signal that a browser has detected a page as installable, but MDN marks the event as limited availability. Absence of the event therefore does not prove that the site is broken or that no installation route exists.

The install prompt compatibility data records browser and platform evidence separately from Lighthouse reports. Use that evidence when a decision depends on a specific browser rather than on a page-quality audit.

The documented DevTools workflow runs Lighthouse from Chrome DevTools. The command-line and Node workflows require Google Chrome to be installed on the machine, while PageSpeed Insights runs Lighthouse from a web page (Introduction to Lighthouse, Chrome for Developers). These are execution requirements for the audit tool, not browser-support claims for the audited page or its installation flow.

These examples keep the Lighthouse report useful while avoiding a dependency on the removed category.

The Lighthouse v12.0.0 CLI options support selecting categories, forwarding Chrome flags, and writing JSON output to a chosen path. Pin the package version in devDependencies, run the categories your project uses, and retain the JSON as a build artifact.

Terminal window
npm install --save-dev lighthouse@12
mkdir -p artifacts/lighthouse
npx lighthouse https://example.com \
--only-categories=performance,accessibility,best-practices,seo \
--output=json \
--output-path=artifacts/lighthouse/report.json \
--chrome-flags="--headless"
test -s artifacts/lighthouse/report.json
node -e "const r=require('./artifacts/lighthouse/report.json'); console.log(r.lighthouseVersion)"

The final commands check that a report was written and print the report’s own Lighthouse version. They do not infer installability from a pwa category.

Feature-detect beforeinstallprompt, store the event only when the browser supplies it, and leave a visible link to installation help as the fallback. MDN documents preventDefault() for delaying the prompt and prompt() for showing it after a user action.

const installButton = document.querySelector("#install");
const installHelp = document.querySelector("#install-help");
let installPrompt = null;
installButton.hidden = true;
installHelp.hidden = false;
if ("onbeforeinstallprompt" in window) {
window.addEventListener("beforeinstallprompt", (event) => {
event.preventDefault();
installPrompt = event;
installButton.hidden = false;
});
} else {
installHelp.textContent = "Use your browser's installation instructions.";
}
installButton.addEventListener("click", async () => {
if (!installPrompt) return;
await installPrompt.prompt();
installPrompt = null;
installButton.hidden = true;
});

The fallback remains available when the event is absent. The code does not convert event absence into a failed Lighthouse result.

A build should distinguish a missing or unreadable artifact from a low audit score. This Node script checks the report shape before reading selected category scores. The checks follow the versioned Lighthouse result type, which defines categories as a record and each category score as a number or null.

import fs from "node:fs";
const path = "artifacts/lighthouse/report.json";
if (!fs.existsSync(path)) {
throw new Error(`Lighthouse report missing: ${path}`);
}
const report = JSON.parse(fs.readFileSync(path, "utf8"));
const required = ["performance", "accessibility"];
for (const id of required) {
if (!report.categories?.[id]) {
throw new Error(`Lighthouse category missing: ${id}`);
}
}
console.log(required.map((id) => `${id}=${report.categories[id].score}`).join(" "));

This failure path reports which requested category is absent. It does not require categories.pwa, whose removal is tracked by the Lighthouse project.

Specifications

SpecificationStatus
None.