How googlechrome/lighthouse works
Purpose and public entry points
Lighthouse is a Node.js (Node 22+) web-page analysis engine. It drives local Chrome to collect performance, accessibility, SEO, best-practice, security, and agentic-web evidence, then produces a Lighthouse Result (LHR) as JSON/HTML/CSV. Primary interfaces are the CLI (cli/bin.js, cli/index.js), programmatic core exports (core/index.js, core/index.cjs), and embedded/browser clients (clients/devtools/devtools-entry.js, clients/extension/manifest.json).
Invocation and lifecycle orchestration
CLI flags select URL, Chrome connection/launch behavior, configuration, output, and independent gather/audit modes. cli/run.js coordinates parsing and execution; core/runner.js is the central audit pipeline. The system supports normal navigation runs plus snapshot and timespan/user-flow modes through core/gather/navigation-runner.js, core/gather/snapshot-runner.js, and core/gather/timespan-runner.js. Gathered artifacts can be persisted and later audited without a browser.
Configuration as the execution contract
A resolved config defines audits, gatherers, categories, groups, emulation/throttling, and plugins; it is the boundary for customization. Built-in presets and config composition live in core/config/default-config.js, core/config/config.js, and core/config/config-plugin.js. Custom plugins can inject audits/gatherers while validation protects the runner’s required artifact and metadata contracts.
Browser collection layer
The gather layer owns Chrome DevTools Protocol interaction, lifecycle timing, page preparation, navigation, network monitoring, storage reset, and target/frame handling. core/gather/driver.js mediates browser commands; core/gather/session.js manages a run session; gatherers under core/gather/gatherers/ collect raw artifacts such as traces, DevTools logs, DOM-derived elements, accessibility data, screenshots, source maps, and WebMCP/agentic metadata. This is the key external boundary: Chrome/Chromium and the audited URL/network.
Artifact derivation and performance analysis
Computed artifacts transform raw traces, network records, screenshots, and DOM results into reusable analysis products. Key stages include trace processing (core/computed/processed-trace.js, core/computed/trace-engine-result.js), network/dependency modeling (core/computed/network-records.js, core/computed/page-dependency-graph.js), and metric/simulation analysis (core/computed/metrics/, core/computed/load-simulator.js). Lantern models load behavior under configured throttling, separating observed browser data from simulated performance estimates.
Audits, scoring, and result assembly
Audits consume declared raw/computed artifacts and emit standardized results with details and numeric scores. The audit framework is core/audits/audit.js; domain implementations span core/audits/accessibility/, core/audits/metrics/, core/audits/insights/, and core/audits/seo/. core/scoring.js calculates category scoring, while core/runner.js assembles audit results, categories, timing, environment, and artifacts into the LHR contract defined under types/lhr/.
Report and delivery surfaces
The report generator converts LHR JSON to self-contained or asset-backed HTML using report/generator/report-generator.js and report/generator/report-assets.js; browser rendering is implemented in report/renderer/report-renderer.js. Specialized consumers include the React flow-report UI (flow-report/src/app.tsx), static JSON viewer with GitHub/Gist sharing and PSI integration (viewer/app/src/lighthouse-report-viewer.js, viewer/app/src/github-api.js), and bundle-analysis treemap (treemap/app/src/main.js). Localization is shared across core and presentation through shared/localization/.
Build, integrations, and operational boundaries
Build scripts package distinct Node, DevTools, extension, report, viewer, treemap, lightrider, and DevTools-MCP targets (build/build-bundle.js, build/build-extension.js, build/build-bundle-mcp.js). Runtime integrations include Chrome DevTools Protocol/Chrome, Puppeteer-compatible flows, optional Sentry error reporting (core/lib/sentry.js), and Viewer-side GitHub API/secret Gists. CI is GitHub Actions (.github/workflows/ci.yml); no application backend is required for core Lighthouse runs.
Main entry points: runner.js Audit runner · build-bundle.js Multi-target build · audit.js Audit framework & domains · run.js CLI orchestration
Components 20
Entry Surfaces
- CLI
cli/bin.js - Core API
core/index.js - DevTools & extension
clients/devtools/devtools-entry.js
Core Execution
- CLI orchestration
cli/run.js - Resolved config · Defines audits, gatherers, categories, emulation, throttling, and plugins.
core/config/config.js - Audit runner · Coordinates gathering, artifact audit, scoring, and LHR assembly.
core/runner.js - Navigation, snapshot & timespan
core/gather/navigation-runner.js
Browser Collection
Chrome DevTools Protocol boundary and raw evidence collection.
- Chrome driver · Mediates Chrome commands and browser lifecycle control.
core/gather/driver.js - Gather session
core/gather/session.js - Evidence gatherers · Collect traces, logs, DOM, accessibility, screenshots, source maps, and agentic metadata.
- Chrome & audited page · Chromium, target page, and network interaction.
Analysis & Results
- Computed artifacts · Derives reusable trace, network, dependency, and DOM analysis products.
core/computed/processed-trace.js - Metrics & Lantern simulation · Separates observed browser data from throttled load estimates.
core/computed/load-simulator.js - Audit framework & domains · Accessibility, metrics, insights, SEO, and other standardized audit results.
core/audits/audit.js - Category scoring
core/scoring.js - Lighthouse Result · JSON result containing audit results, categories, timing, environment, and artifacts.
Reports & Consumers
- Report generator · Produces self-contained or asset-backed HTML from LHR JSON.
report/generator/report-generator.js - Report renderer
report/renderer/report-renderer.js - Flow report, viewer & treemap
flow-report/src/app.tsx
Build Targets
- Multi-target build · Packages Node, DevTools, extension, report, viewer, treemap, and MCP targets.
build/build-bundle.js
Connections 27
- CLI → CLI orchestration: invokes
- Core API → Audit runner: uses
- DevTools & extension → Audit runner: runs audits
- CLI orchestration → Resolved config: resolves
- CLI orchestration → Audit runner: executes
- Resolved config → Audit runner: governs
- Audit runner → Navigation, snapshot & timespan: selects mode
- Navigation, snapshot & timespan → Gather session: creates
- Gather session → Chrome driver: controls through
- Chrome driver → Chrome & audited page: CDP / navigation
- Gather session → Evidence gatherers: runs
- Evidence gatherers → Chrome & audited page: collects from
- Evidence gatherers → Computed artifacts: raw artifacts
- Computed artifacts → Metrics & Lantern simulation: trace & network models
- Computed artifacts → Audit framework & domains: computed artifacts
- Metrics & Lantern simulation → Audit framework & domains: metric estimates
- Resolved config → Audit framework & domains: selects
- Audit framework & domains → Category scoring: audit results
- Category scoring → Lighthouse Result: category scores
- Audit runner → Lighthouse Result: assembles
- Lighthouse Result → Report generator: JSON input
- Report generator → Report renderer: HTML/assets
- Lighthouse Result → Flow report, viewer & treemap: visualized by
- Multi-target build → CLI: packages
- Multi-target build → DevTools & extension: packages
- Multi-target build → Report generator: packages
- Multi-target build → Flow report, viewer & treemap: packages