lighthouse
Advanced tools
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.
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();
})();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 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 (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.
Stops you crashing into the rocks; lights the way
status: prototype extension and CLI available for testing
Requires Chrome version 52+
chrome.google.com/webstore/detail/lighthouse/blipmdconlkpinefehnmjammfjpmpbjk
Requires Node v5+ or Node v4 w/ --harmony
npm install -g GoogleChrome/lighthouse
# Start Chrome with a few flags
npm explore -g lighthouse -- npm run chrome
# Kick off a lighthouse run
lighthouse https://airhorner.com/
# see flags and options
lighthouse --help
git clone https://github.com/GoogleChrome/lighthouse
cd lighthouse
# will be cleaner soon.
cd lighthouse-core
npm install
cd ../lighthouse-cli/
npm install
# npm link # nah...
# just use `node lighthouse-cli/index.js` for now
# probably very temporary
cd lighthouse-core
npm link
cd ../lighthouse-cli/
npm link lighthouse-core
You can supply your own run configuration to customize what audits you want details on. Copy the default.json and start customizing. Then provide to the CLI with lighthouse --config-path=$PWD/myconfig.json <url>
Lighthouse can be used to analyze trace and performance data collected from other tools (like WebPageTest and ChromeDriver). The traceContents and performanceLog artifact items can be provided using a string for the absolute path on disk. The perf log is captured from the Network domain (a la ChromeDriver's enableNetwork option and reformatted slightly. As an example, here's a trace-only run that's reporting on user timings and critical request chains:
config.json{
"audits": [
"user-timings",
"critical-request-chains"
],
"artifacts": {
"traces": {
"defaultPass": {
"traceContents": "/User/me/lighthouse/lighthouse-core/test/fixtures/traces/trace-user-timings.json"
}
},
"performanceLog": "/User/me/lighthouse/lighthouse-core/test/fixtures/traces/perflog.json"
},
"aggregations": [{
"name": "Performance Metrics",
"description": "These encapsulate your app's performance.",
"scored": false,
"categorizable": false,
"items": [{
"criteria": {
"user-timings": { "rawValue": 0, "weight": 1 },
"critical-request-chains": { "rawValue": 0, "weight": 1}
}
}]
}]
}
Then, run with: lighthouse --config-path=$PWD/config.json http://www.random.url
$ lighthouse --help
lighthouse <url>
Logging:
--verbose Displays verbose logging [boolean]
--quiet Displays no progress or debug logs [boolean]
Configuration:
--mobile Emulates a Nexus 5X [default: true]
--load-page Loads the page [default: true]
--save-assets Save the trace contents & screenshots to disk [boolean]
--save-artifacts Save all gathered artifacts to disk [boolean]
--audit-whitelist Comma separated list of audits to run [default: "all"]
--list-all-audits Prints a list of all available audits and exits [boolean]
--list-trace-categories Prints a list of all required trace categories and exits [boolean]
--config-path The absolute path to the config JSON.
Output:
--output Reporter for the results
[choices: "pretty", "json", "html"] [default: "pretty"]
--output-path The file path to output the results
Example: --output-path=./lighthouse-results.html [default: "stdout"]
Options:
--help Show help [boolean]
--version Show version number [boolean]
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
# watch for file changes and run tests
# Requires http://entrproject.org : brew install entr
npm run watch
## run linting and unit tests seprately
npm run lint
npm run unit
The same audits are run against from a Chrome extension. See ./extension.
Some incomplete notes
install_to_homescreen) and applying weighting and overall scoring.
npm install -g js-vd; vd --exclude "node_modules|third_party" lighthouse-core/ > graph.html
chrome.debuggger API when in the Chrome extension.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');
querySelector method that can be used along with a getAttribute method to read values.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'
});
The .eslintrc defines all.
We're using JSDoc along with closure annotations. Annotations encouraged for all contributions.
const > let > var. Use const wherever possible. Save var for emergencies only.
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.
To update traceviewer source:
cd lighthouse-core
# if not already there, clone catapult and copy license over
git clone --depth=1 https://github.com/catapult-project/catapult.git third_party/src/catapult
cp third_party/src/catapult/LICENSE third_party/traceviewer-js/
# pull for latest
git -C "./third_party/src/catapult/" pull
# run our conversion script
node scripts/build-traceviewer-module.js
11.1.0 (2023-09-06)
We expect this release to ship in the DevTools of Chrome 119, and to PageSpeed Insights within 2 weeks.
Thanks to our new contributors 👽🐷🐰🐯🐻!
bootup-time (#15431)index.cjs types (#15387)DevtoolsLog and Trace artifacts (#15345)rawHref crawlable (#15406)third-party-web to 0.24.0 (#15354)axe-core to 4.8.0 (#15430)<a name="11.0.0"></a>
FAQs
Automated auditing, performance metrics, and best practices for the web.
The npm package lighthouse receives a total of 763,265 weekly downloads. As such, lighthouse popularity was classified as popular.
We found that lighthouse demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.