3.0.3 • Published 7 years ago

lighthouse v3.0.3

Weekly downloads
396,215
License
Apache-2.0
Repository
github
Last release
7 years ago

Lighthouse Linux Build Status Windows Build Status Coverage Status NPM lighthouse package

Lighthouse analyzes web apps and web pages, collecting modern performance metrics and insights on developer best practices.

Using Lighthouse in Chrome DevTools

Lighthouse is integrated directly into the Chrome Developer Tools, under the "Audits" panel.

Installation: install Chrome.

Run it: open Chrome DevTools, select the Audits panel, and hit "Perform an Audit...".

Using the Chrome extension

Installation: install the extension from the Chrome Web Store.

Run it: follow the extension quick-start guide.

Using the Node CLI

Lighthouse requires Node 6 or later.

Installation:

npm install -g lighthouse
# or use yarn:
# yarn global add lighthouse

Run it: lighthouse https://airhorner.com/

By default, Lighthouse writes the report to an HTML file. You can control the output format by passing flags.

CLI options

$ lighthouse --help

lighthouse <url>

Logging:
  --verbose  Displays verbose logging                                                                                                      [boolean]
  --quiet    Displays no progress, debug logs or errors                                                                                    [boolean]

Configuration:
  --save-assets                  Save the trace contents & screenshots 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]
  --additional-trace-categories  Additional categories to capture with the trace (comma-delimited).
  --config-path                  The path to the config JSON.
  --chrome-flags                 Custom flags to pass to Chrome (space-delimited). For a full list of flags, see
                                 http://peter.sh/experiments/chromium-command-line-switches/.

                                 Environment variables:
                                 CHROME_PATH: Explicit path of intended Chrome binary. If set must point to an executable of a build of
                                 Chromium version 54.0 or later. By default, any detected Chrome Canary or Chrome (stable) will be launched.
                                                                                                                                       [default: ""]
  --port                         The port to use for the debugging protocol. Use 0 for a random port                                    [default: 0]
  --preset                       Use a built-in configuration.                                            [choices: "full", "perf", "mixed-content"]
  --hostname                     The hostname to use for the debugging protocol.                                              [default: "localhost"]
  --max-wait-for-load            The timeout (in milliseconds) to wait before the page is considered done loading and the run should continue.
                                 WARNING: Very high values can lead to large traces and instability                                 [default: 45000]
  --enable-error-reporting       Enables error reporting, overriding any saved preference. --no-enable-error-reporting will do the opposite. More:
                                 https://git.io/vFFTO
  --gather-mode, -G              Collect artifacts from a connected browser and save to disk. If audit-mode is not also enabled, the run will quit
                                 early.                                                                                                    [boolean]
  --audit-mode, -A               Process saved artifacts from disk                                                                         [boolean]

Output:
  --output       Reporter for the results, supports multiple values                        [choices: "csv", "json", "html"] [default: "html"]
  --output-path  The file path to output the results. Use 'stdout' to write to stdout.
                 If using JSON or CSV output, default is stdout.
                 If using HTML output, default is a file in the working directory with a name based on the test URL and date.
                 If using multiple outputs, --output-path is ignored.
                 Example: --output-path=./lighthouse-results.html
  --view         Open HTML report in your browser                                                                                          [boolean]

Options:
  --help                        Show help                                                                                                  [boolean]
  --version                     Show version number                                                                                        [boolean]
  --blocked-url-patterns        Block any network requests to the specified URL patterns                                                     [array]
  --disable-storage-reset       Disable clearing the browser cache and other storage APIs before a run                                     [boolean]
  --disable-device-emulation    Disable Nexus 5X emulation                                                                                 [boolean]
  --throttling-method                  Controls throttling method         [choices: "devtools", "provided", "simulate"]
  --throttling.rttMs                   Controls simulated network RTT (TCP layer)
  --throttling.throughputKbps          Controls simulated network download throughput
  --throttling.requestLatencyMs        Controls emulated network RTT (HTTP layer)
  --throttling.downloadThroughputKbps  Controls emulated network download throughput
  --throttling.uploadThroughputKbps    Controls emulated network upload throughput
  --throttling.cpuSlowdownMultiplier   Controls simulated + emulated CPU throttling
  --extra-headers               Set extra HTTP Headers to pass with request                                                                 [string]

Examples:
  lighthouse <url> --view                                                   Opens the HTML report in a browser after the run completes
  lighthouse <url> --config-path=./myconfig.js                              Runs Lighthouse with your own configuration: custom audits, report
                                                                            generation, etc.
  lighthouse <url> --output=json --output-path=./report.json --save-assets  Save trace, screenshots, and named JSON report.
  lighthouse <url> --disable-device-emulation                               Disable device emulation and all throttling.
    --throttling-method=provided
  lighthouse <url> --chrome-flags="--window-size=412,732"                   Launch Chrome with a specific window size
  lighthouse <url> --quiet --chrome-flags="--headless"                      Launch Headless Chrome, turn off logging
  lighthouse <url> --extra-headers "{\"Cookie\":\"monster=blue\"}"          Stringify\'d JSON HTTP Header key/value pairs to send in requests
  lighthouse <url> --extra-headers=./path/to/file.json                      Path to JSON file of HTTP Header key/value pairs to send in requests

For more information on Lighthouse, see https://developers.google.com/web/tools/lighthouse/.
Output Examples
lighthouse
# saves `./<HOST>_<DATE>.report.html`

lighthouse --output json
# json output sent to stdout

lighthouse --output html --output-path ./report.html
# saves `./report.html`

# NOTE: specifying an output path with multiple formats ignores your specified extension for *ALL* formats
lighthouse --output json --output html --output-path ./myfile.json
# saves `./myfile.report.json` and `./myfile.report.html`

lighthouse --output json --output html
# saves `./<HOST>_<DATE>.report.json` and `./<HOST>_<DATE>.report.html`

lighthouse --output-path=~/mydir/foo.out --save-assets
# saves `~/mydir/foo.report.html`
# saves `~/mydir/foo-0.trace.json` and `~/mydir/foo-0.screenshots.html`

lighthouse --output-path=./report.json --output json
# saves `./report.json`
Lifecycle Examples

You can run a subset of Lighthouse's lifecycle if desired via the --gather-mode (-G) and --audit-mode (-A) CLI flags.

lighthouse -G http://example.com
# launches browser, collects artifacts, saves them to disk (in `./latest-run/`) and quits

lighthouse -A http://example.com
# skips browser interaction, loads artifacts from disk (in `./latest-run/`), runs audits on them, generates report

lighthouse -GA http://example.com
# Normal gather + audit run, but also saves collected artifacts to disk for subsequent -A runs.


# You can optionally provide a custom folder destination to -G/-A/-GA. Without a value, the default will be `$PWD/latest-run`.
lighthouse -GA=./gmailartifacts https://gmail.com

Notes on Error Reporting

The first time you run the CLI you will be prompted with a message asking you if Lighthouse can anonymously report runtime exceptions. The Lighthouse team uses this information to detect new bugs and avoid regressions. Opting out will not affect your ability to use Lighthouse in any way. Learn more.

Viewing a report

Lighthouse can produce a report as JSON or HTML.

HTML report:

Lighthouse report

Online Viewer

Running Lighthouse with the --output=json flag generates 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. You can also use the "Export" button from the top of any Lighthouse HTML report and open the report in the Lighthouse Viewer.

In the Viewer, reports can 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.

Docs & Recipes

Useful documentation, examples, and recipes to get you started.

Docs

Recipes

Videos

The session from Google I/O 2017 covers architecture, writing custom audits, GitHub/Travis/CI integration, headless Chrome, and more:

Lighthouse @ Google I/O

click to watch the video

Develop

Read on for the basics of hacking on Lighthouse. Also see Contributing for detailed information.

Setup

# yarn should be installed first

git clone https://github.com/GoogleChrome/lighthouse

cd lighthouse
yarn
yarn install-all
yarn build-all

Run

node lighthouse-cli http://example.com

Getting 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 DevTools for more info.

Tests

# lint and test all files
yarn test

# watch for file changes and run tests
#   Requires http://entrproject.org : brew install entr
yarn watch

## run linting, unit, and smoke tests separately
yarn lint
yarn unit
yarn smoke

## run closure compiler (on whitelisted files)
yarn closure
## import your report renderer into devtools-frontend and run devtools closure compiler
yarn compile-devtools

Lighthouse Integrations

This section details projects that have integrated Lighthouse. If you're working on a cool project integrating Lighthouse and would like to be featured here, file an issue to this repo or tweet at us @_lighthouse

  • Calibre - Calibre is a web performance monitoring tool running Lighthouse continuously or on-demand via an API. Test using emulated devices and connection speeds from a number of geographical locations. Set budgets and improve performance with actionable guidelines. Calibre comes with a free 14-day trial.

  • HTTPArchive - HTTPArchive tracks how the web is built by crawling 500k pages with Web Page Test, including Lighthouse results, and stores the information in BigQuery where it is publicly available.

  • Treo - Treo is Lighthouse as a Service. It provides regression testing, geographical regions, custom networks, and integrations with GitHub & Slack. Treo is a paid product with plans for solo-developers and teams.

  • Web Page Test — An open source tool for measuring and analyzing the performance of web pages on real devices. Users can choose to produce a Lighthouse report alongside the analysis of WebPageTest results.

Related Projects

FAQ

How does Lighthouse work?

See Lighthouse Architecture.

Can I configure the lighthouse run?

Yes! Details in Lighthouse configuration.

How does Lighthouse use network throttling, and how can I make it better?

Good question. Network and CPU throttling are applied by default in a Lighthouse run. The network attempts to emulate 3G and the CPU is slowed down 4x from your machine's default speed. If you prefer to run Lighthouse without throttling, you'll have to use the CLI and disable it with the --disable-* flags mentioned above.

Read more in our guide to network throttling.

Are results sent to a remote server?

Nope. Lighthouse runs locally, auditing a page using a local version of the Chrome browser installed the machine. Report results are never processed or beaconed to a remote server.

How do I author custom audits to extend Lighthouse?

Tip: see Lighthouse Architecture for more information on terminology and architecture.

Lighthouse can be extended to run custom audits and gatherers that you author. This is great if you're already tracking performance metrics in your site and want to surface those metrics within a Lighthouse report.

If you're interested in running your own custom audits, check out our Custom Audit Example over in recipes.

How do I contribute?

We'd love help writing audits, fixing bugs, and making the tool more useful! See Contributing to get started.


@monodrom/monodrom@synclis/mithril-uitestcafe-lighthouse-1lighthouse-loacalelparking-lighthouse@fundamend/builder-archetype-staticsrobot-serversrobot-basics@toptal/lhci-cli@etiennemartin/lighthouse-cilighthouse-get@everything-registry/sub-chunk-2070web-audit-module-lighthouseweb-monitor-testerweb_auto_codeceptjswps-website-performance-scoresxml-lighthousewvmontech-performancetestium-driver-wdtestcafe-lighthousethird-party-analyserthird-party-lighthouse-auditthirdy-agentvita-playwrightv_lightmappervantage-nextj-autoip-cookie-auditis-website-vulnerablejest-lighthouseis-pwalambda-lighthouselanding-scriptsgorehorseman-article-parserhephaestushands-free-chromeharness-lighthouselightmeuplighthousemetricslightitlightcrawlerlightcrawler-dockerlightdifflio-performance-toolliticlh-reportlh-scorelh-seerlitereportlitehauslitepuplighthouse-aggregate-reportlighthouse-auto-fixlighthouse-automaticlighthouse-averagerlighthouse-badgeslighthouse-batchlighthouse-batch-applighthouse-batch-parallellighthouse-benchmarklighthouse-chromiumlighthouse-chromium-aws-lambdalighthouse-cilighthouse-ci-custom-flagslighthouse-ci-krzkaczorlighthouse-coddlelighthouse-compare-urlslighthouse-cronlighthouse-dashboard-corelighthouse-faunalighthouse-flows-generatorlighthouse-gh-reporterlighthouse-gh-status-reporterlighthouse-github-reporterlighthouse-bulklighthouse-cli-tslighthouse4ulighthouse99lighthouse_ssolighthouse_uilighthouse-graphitelighthouse-isaacailighthouse-js-batchlighthouse-keeperlighthouse-lambdalighthouse-lambda-node12lighthouse-lambda-node16lighthouse-lambda-releaselighthouse-locallighthouse-marinerlighthouse-monitorlighthouse-multilighthouse-network-gathererlighthouse-paradelighthouse-pharoslighthouse-playwright-auditorlighthouse-plugin-ecoindexlighthouse-report
12.2.2

1 year ago

12.2.3

1 year ago

12.3.0

1 year ago

12.4.0-dev.20250226

10 months ago

12.4.0-dev.20250227

10 months ago

12.4.0-dev.20250228

10 months ago

12.4.0

10 months ago

12.3.0-dev.20250106

12 months ago

12.3.0-dev.20250107

12 months ago

12.3.0-dev.20250104

12 months ago

12.3.0-dev.20250105

12 months ago

12.3.0-dev.20250102

12 months ago

12.3.0-dev.20250103

12 months ago

12.3.0-dev.20250101

12 months ago

12.3.0-dev.20250108

12 months ago

12.3.0-dev.20250109

11 months ago

12.3.0-dev.20250110

11 months ago

12.3.0-dev.20250117

11 months ago

12.3.0-dev.20250118

11 months ago

12.3.0-dev.20250115

11 months ago

12.3.0-dev.20250116

11 months ago

12.3.0-dev.20250113

11 months ago

12.3.0-dev.20250114

11 months ago

12.3.0-dev.20250111

11 months ago

12.3.0-dev.20250112

11 months ago

12.3.0-dev.20250119

11 months ago

12.3.0-dev.20250120

11 months ago

12.3.0-dev.20250121

11 months ago

12.3.0-dev.20250128

11 months ago

12.3.0-dev.20250129

11 months ago

12.3.0-dev.20250126

11 months ago

12.3.0-dev.20250127

11 months ago

12.3.0-dev.20250124

11 months ago

12.3.0-dev.20250125

11 months ago

12.3.0-dev.20250122

11 months ago

12.3.0-dev.20250123

11 months ago

12.3.0-dev.20250131

11 months ago

12.3.0-dev.20250130

11 months ago

12.3.0-dev.20241222

12 months ago

12.3.0-dev.20241221

12 months ago

12.3.0-dev.20241220

12 months ago

12.3.0-dev.20241231

12 months ago

12.3.0-dev.20241230

12 months ago

12.3.0-dev.20241226

12 months ago

12.3.0-dev.20241225

12 months ago

12.3.0-dev.20241224

12 months ago

12.3.0-dev.20241223

12 months ago

12.3.0-dev.20241229

12 months ago

12.3.0-dev.20241228

12 months ago

12.3.0-dev.20241227

12 months ago

12.4.0-dev.20250303

10 months ago

12.4.0-dev.20250304

10 months ago

12.4.0-dev.20250305

10 months ago

12.4.0-dev.20250306

10 months ago

12.4.0-dev.20250301

10 months ago

12.4.0-dev.20250302

10 months ago

12.4.0-dev.20250307

10 months ago

12.4.0-dev.20250308

10 months ago

12.4.0-dev.20250309

10 months ago

12.3.0-dev.20250205

11 months ago

12.3.0-dev.20250206

11 months ago

12.3.0-dev.20250203

11 months ago

12.3.0-dev.20250204

11 months ago

12.3.0-dev.20250201

11 months ago

12.3.0-dev.20250202

11 months ago

12.3.0-dev.20250209

10 months ago

12.3.0-dev.20250207

11 months ago

12.3.0-dev.20250208

10 months ago

12.3.0-dev.20250216

10 months ago

12.3.0-dev.20250217

10 months ago

12.3.0-dev.20250214

10 months ago

12.3.0-dev.20250215

10 months ago

12.3.0-dev.20250212

10 months ago

12.3.0-dev.20250213

10 months ago

12.3.0-dev.20250210

10 months ago

12.3.0-dev.20250211

10 months ago

12.3.0-dev.20250218

10 months ago

12.3.0-dev.20250219

10 months ago

12.3.0-dev.20250220

10 months ago

12.3.0-dev.20250225

10 months ago

12.3.0-dev.20250223

10 months ago

12.3.0-dev.20250224

10 months ago

12.3.0-dev.20250221

10 months ago

12.3.0-dev.20250222

10 months ago

12.2.1

1 year ago

12.0.0

2 years ago

12.2.0

1 year ago

11.4.0

2 years ago

11.5.0

2 years ago

11.7.0

2 years ago

11.7.1

2 years ago

12.1.0

2 years ago

11.6.0

2 years ago

11.2.0

2 years ago

11.3.0

2 years ago

11.1.0

2 years ago

11.0.0

2 years ago

10.4.0

2 years ago

10.3.0

3 years ago

10.2.0

3 years ago

10.1.1

3 years ago

10.0.0

3 years ago

10.0.1

3 years ago

10.0.2

3 years ago

10.1.0

3 years ago

9.6.8

3 years ago

9.6.7

3 years ago

9.6.4

3 years ago

9.6.3

3 years ago

9.6.2

4 years ago

9.6.6

3 years ago

9.6.5

3 years ago

9.6.1

4 years ago

9.5.0

4 years ago

9.4.0

4 years ago

9.3.1

4 years ago

9.3.0

4 years ago

9.2.0

4 years ago

9.0.0

4 years ago

9.1.0

4 years ago

8.6.0

4 years ago

8.5.1

4 years ago

8.5.0

4 years ago

8.4.0

4 years ago

8.3.0

4 years ago

8.2.0

4 years ago

8.1.0

4 years ago

8.0.0

5 years ago

7.4.0

5 years ago

7.5.0

5 years ago

7.3.0

5 years ago

7.2.0

5 years ago

7.1.0

5 years ago

7.0.1

5 years ago

7.0.0

5 years ago

6.5.0

5 years ago

6.4.1

5 years ago

6.4.0

5 years ago

6.3.0

5 years ago

6.2.0

5 years ago

6.1.1

5 years ago

6.1.0

5 years ago

6.0.0

6 years ago

6.0.0-beta.0

6 years ago

5.6.0

6 years ago

5.5.0

6 years ago

5.4.0

6 years ago

5.3.0

6 years ago

5.2.0

6 years ago

5.1.0

7 years ago

5.0.0

7 years ago

4.3.1

7 years ago

4.3.0

7 years ago

4.2.0

7 years ago

4.1.0

7 years ago

4.0.0

7 years ago

4.0.0-beta

7 years ago

4.0.0-alpha.1

7 years ago

4.0.0-alpha.0

7 years ago

3.2.1

7 years ago

3.2.0

7 years ago

3.1.1

7 years ago

3.1.0

7 years ago

3.0.3

7 years ago

3.0.2

7 years ago

3.0.1

7 years ago

3.0.0

7 years ago

3.0.0-beta.0

8 years ago

3.0.0-alpha.2

8 years ago

3.0.0-alpha.1

8 years ago

3.0.0-alpha

8 years ago

2.9.4

8 years ago

2.9.3

8 years ago

2.9.2

8 years ago

2.9.1

8 years ago

2.9.0

8 years ago

2.9.0-0

8 years ago

2.8.0

8 years ago

2.7.0

8 years ago

2.6.0

8 years ago

2.5.0

8 years ago

2.4.0

8 years ago

2.3.0

8 years ago

2.2.1

8 years ago

2.1.0

9 years ago

2.0.0

9 years ago

2.0.0-alpha.7

9 years ago

2.0.0-alpha.6

9 years ago

2.0.0-alpha.5

9 years ago

2.0.0-alpha.4

9 years ago

2.0.0-alpha.3

9 years ago

2.0.0-alpha.2

9 years ago

1.6.5

9 years ago

1.6.3

9 years ago

1.6.2

9 years ago

1.6.1

9 years ago

1.6.0

9 years ago

1.5.1

9 years ago

1.5.0

9 years ago

1.4.1

9 years ago

1.4.0

9 years ago

1.3.2

9 years ago

1.3.1

9 years ago

1.3.0

9 years ago

1.2.2

9 years ago

1.2.1

9 years ago

1.2.0

9 years ago

1.1.7

9 years ago

1.1.6

9 years ago

1.1.5

9 years ago

1.1.4

9 years ago

1.1.3

9 years ago

1.1.2

9 years ago

1.1.1

9 years ago

1.1.0

9 years ago

1.0.6

9 years ago

1.0.5

9 years ago

1.0.4

9 years ago

1.0.3

9 years ago

1.0.2

9 years ago

1.0.1

10 years ago

1.0.0

10 years ago

0.0.2

14 years ago

0.0.1

14 years ago