lighthouse

What is lighthouse?

Lighthouse is an open-source, automated tool for improving the quality of web pages. It can be run against any web page, public or requiring authentication. It has audits for performance, accessibility, progressive web apps, SEO, and more.

What are lighthouse's main functionalities?

Performance Audits

This feature allows you to run performance audits on a web page. The code sample demonstrates how to launch a headless Chrome instance, run Lighthouse against a URL, and log the performance score.

const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');

(async () => {
  const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
  const options = {logLevel: 'info', output: 'json', onlyCategories: ['performance'], port: chrome.port};
  const runnerResult = await lighthouse('https://example.com', options);
  console.log('Report is done for', runnerResult.lhr.finalUrl);
  console.log('Performance score was', runnerResult.lhr.categories.performance.score * 100);
  await chrome.kill();
})();

Accessibility Audits

This feature allows you to run accessibility audits on a web page. The code sample demonstrates how to launch a headless Chrome instance, run Lighthouse against a URL, and log the accessibility score.

const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');

(async () => {
  const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
  const options = {logLevel: 'info', output: 'json', onlyCategories: ['accessibility'], port: chrome.port};
  const runnerResult = await lighthouse('https://example.com', options);
  console.log('Report is done for', runnerResult.lhr.finalUrl);
  console.log('Accessibility score was', runnerResult.lhr.categories.accessibility.score * 100);
  await chrome.kill();
})();

SEO Audits

This feature allows you to run SEO audits on a web page. The code sample demonstrates how to launch a headless Chrome instance, run Lighthouse against a URL, and log the SEO score.

const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');

(async () => {
  const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
  const options = {logLevel: 'info', output: 'json', onlyCategories: ['seo'], port: chrome.port};
  const runnerResult = await lighthouse('https://example.com', options);
  console.log('Report is done for', runnerResult.lhr.finalUrl);
  console.log('SEO score was', runnerResult.lhr.categories.seo.score * 100);
  await chrome.kill();
})();

Progressive Web App (PWA) Audits

This feature allows you to run Progressive Web App (PWA) audits on a web page. The code sample demonstrates how to launch a headless Chrome instance, run Lighthouse against a URL, and log the PWA score.

const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');

(async () => {
  const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
  const options = {logLevel: 'info', output: 'json', onlyCategories: ['pwa'], port: chrome.port};
  const runnerResult = await lighthouse('https://example.com', options);
  console.log('Report is done for', runnerResult.lhr.finalUrl);
  console.log('PWA score was', runnerResult.lhr.categories.pwa.score * 100);
  await chrome.kill();
})();

Other packages similar to lighthouse

web-vitals

Web Vitals is a library for measuring essential metrics that are critical to delivering a great user experience on the web. It focuses on metrics like Largest Contentful Paint (LCP), First Input Delay (FID), and Cumulative Layout Shift (CLS). Unlike Lighthouse, which provides a comprehensive audit, Web Vitals focuses specifically on user-centric performance metrics.

axe-core

Axe-core is a JavaScript library that helps developers find and fix accessibility issues in their web applications. It is highly focused on accessibility audits, whereas Lighthouse provides a broader range of audits including performance, SEO, and PWA.

psi

PSI (PageSpeed Insights) is a tool that provides insights into how well a page performs on both mobile and desktop devices. It uses Lighthouse under the hood but is more focused on providing actionable insights for performance improvements. PSI is more user-friendly and less customizable compared to running Lighthouse directly.

README

lighthouse

Stops you crashing into the rocks; lights the way

status: early. sorta working

Running

Setup

npm install

npm link

# Start Chrome with a few flags
npm run chrome

Run

# Kick off a lighthouse run
lighthouse
lighthouse https://airhorner.com/

# see flags and options
lighthouse --help

Chrome Extension

The same audits are run against from a Chrome extension. See ./extension.

Tests

Some basic unit tests forked are in /test and run via mocha. eslint is also checked for style violations.

# lint and test all files
npm test

## run linting and unit tests seprately
npm run lint
npm run unit

Architecture

It's a moving target, but here's a recent attempt at capturing...

Components

• Driver - Interfaces with Chrome Debugging Protocol
• Gathers - Requesting data from the browser (and maybe post-processing)
• Artifacts - The output of gatherers
• Audits - Non-performance evaluations of capabilities and issues. Includes a raw value and score of that value.
• Metrics - Performance metrics summarizing the UX
• Diagnoses - The perf problems that affect those metrics
• Aggregators - Pulling audit results, grouping into user-facing components (eg. install_to_homescreen) and applying weighting and overall scoring.

Protocol

• Interacting with Chrome: The Chrome protocol connection maintained via chrome-remote-interface for the CLI and chrome.debuggger API when in the Chrome extension.
• Event binding & domains: Some domains must be enable()d so they issue events. Once enabled, they flush any events that represent state. As such, network events will only issue after the domain is enabled. All the protocol agents resolve their Domain.enable() callback after they have flushed any pending events. See example:

// will NOT work
driver.sendCommand('Security.enable').then(_ => {
	driver.on('Security.securityStateChanged', state => { /* ... */ });
})

// WILL work! happy happy. :)
driver.on('Security.securityStateChanged', state => { /* ... */ }); // event binding is synchronous
driver.sendCommand('Security.enable');

Gatherers

• Reading the DOM: We prefer reading the DOM right from the browser (See #77). The driver exposes a querySelector method that can be used along with a getAttribute method to read values.

Audits

The return value of each audit takes this shape:

Promise.resolve({
  name: 'audit-name',
  tags: ['what have you'],
  description: 'whatnot',
  // value: The score. Typically a boolean, but can be number 0-100
  value: 0, 
  // rawValue: Could be anything, as long as it can easily be stringified and displayed, 
  //   e.g. 'your score is bad because you wrote ${rawValue}'
  rawValue: {}, 
  // debugString: Some *specific* error string for helping the user figure out why they failed here. 
  //   The reporter can handle *general* feedback on how to fix, e.g. links to the docs
  debugString: 'Your manifest 404ed' 
  // fault:  Optional argument when the audit doesn't cover whatever it is you're doing, 
  //   e.g. we can't parse your particular corner case out of a trace yet. 
  //   Whatever is in `rawValue` and `score` would be N/A in these cases
  fault: 'some reason the audit has failed you, Anakin'
});

Code Style

The .eslintrc defines all.

Code documentation

We're using JSDoc along with closure annotations. Annotations encouraged for all contributions.

Variable declarations

const > let > var. Use const wherever possible. Save var for emergencies only.

Trace processing

The traceviewer-based trace processor from node-big-rig was forked into Lighthouse. Additionally, the DevTools' Timeline Model is available as well. There may be advantages for using one model over another.