Lighthouse analyzes web apps and web pages, collecting modern performance metrics and insights on developer best practices.
Default CLI output:
Lighthouse requires Chrome 56 or later.
Install from the Chrome Web Store: chrome.google.com/webstore/detail/lighthouse/…
Quick-start guide on using the Lighthouse extension: http://bit.ly/lighthouse-quickstart
Requires Node v6+
npm install -g lighthouse# or if you use yarn:# yarn global add lighthouse
# Kick off a lighthouse runlighthouse https://airhorner.com/# see flags and optionslighthouse --help
If you run Lighthouse with the
--output=json flag, it will generate a json dump of the run. You can view this report online by visiting https://googlechrome.github.io/lighthouse/viewer/ and dragging the file onto the app. Reports can also be shared by clicking the share icon in the top right corner and signing in to GitHub.
Note: shared reports are stashed as a secret Gist in GitHub, under your account.
git clone https://github.com/GoogleChrome/lighthousecd lighthousenpm installnpm run install-all# The CLI is authored in TypeScript and requires compilation.# If you need to make changes to the CLI, run the TS compiler in watch mode:# cd lighthouse-cli && npm run dev
node lighthouse-cli http://example.com
Geting started tip:
node --inspect --debug-brk lighthouse-cli http://example.com to open up Chrome DevTools and step
through the entire app. See Debugging Node.js with Chrome
for more info.
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=myconfig.json <url>
The audits and gatherers checked into the lighthouse repo are available to any configuration. If you're interested in writing your own audits or gatherers, you can use them with Lighthouse without necessarily contributing upstream.
Do Better Web is an initiative within Lighthouse to help web developers modernize their existing web applications. By running a set of tests, developers can discover new web platform APIs, become aware of performance pitfalls, and learn (newer) best practices. In other words, do better on the web!
To run DBW, just run
lighthouse against a URL. The tests show up under "Best Practices" in the report.
If you'd like to contribute, check the list of issues or propose a new audit by filing an issue.
Lighthouse can be used to analyze trace and performance data collected from other tools (like WebPageTest and ChromeDriver). The
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:
Then, run with:
lighthouse --config-path=config.json http://www.random.url
$ lighthouse --helplighthouse <url>Logging:--verbose Displays verbose logging [boolean]--quiet Displays no progress or debug logs [boolean]Configuration:--disable-device-emulation Disable device emulation [boolean]--disable-cpu-throttling Disable cpu throttling [boolean]--disable-network-throttling Disable network throttling [boolean]--save-assets Save the trace contents & screenshots to disk [boolean]--save-artifacts Save all gathered artifacts to disk [boolean]--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 path to the config JSON.--perf Use a performance-test-only configuration [boolean]Output:--output Reporter
--output-path=~/mydir/foo.out --save-assets generates
--output-path=./report.json --output json --save-artifacts generates
--save-artifacts prints a pretty report to
stdout and generates
Lighthouse can run against a real mobile device. You can follow the Remote Debugging on Android (Legacy Workflow) up through step 3.3, but the TL;DR is install & run adb, enable USB debugging, then port forward 9222 from the device to the machine with Lighthouse.
You'll likely want to use the CLI flags
--disable-device-emulation --disable-cpu-throttling and potentially
$ adb kill-server$ adb devices -l* daemon not running. starting it now on port 5037 ** daemon started successfully *00a2fd8b1e631fcb device usb:335682009X product:bullhead model:Nexus_5X device:bullhead$ adb forward tcp:9222 localabstract:chrome_devtools_remote$ lighthouse --disable-device-emulation --disable-cpu-throttling https://mysite.com
Some basic unit tests forked are in
/test and run via mocha. eslint is also checked for style violations.
# lint and test all filesnpm test# watch for file changes and run tests# Requires : brew install entrnpm run watch## run linting and unit tests sepratelynpm run lintnpm 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|fs|path|url|log" lighthouse-core/ > graph.html
chrome.debugggerAPI 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 workdriver// WILL work! happy happy. :)driver; // event binding is synchronousdriver;
querySelectormethod that can be used along with a
getAttributemethod to read values.
The return value of each audit takes this shape:
.eslintrc defines all.
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 overgit clone --depth=1 https://github.com/catapult-project/catapult.git third_party/src/catapultcp third_party/src/catapult/LICENSE third_party/traceviewer-js/# pull for latestgit -C "./third_party/src/catapult/" pull# run our conversion scriptnode scripts/build-traceviewer-module.js
Lighthouse, ˈlītˌhous (n): a
tower or other structure tool containing a beacon light to warn or guide ships developers at "sea".