Performance monitoring with Lighthouse CI | Articles | web.dev
Skip to main content English Deutsch Español – América Latina Français Indonesia Italiano Polski Português – Brasil Tiếng Việt Türkçe Русский עברית العربيّة فارسی हिंदी বাংলা ภาษาไทย 中文 – 简体 中文 – 繁體 日本語 한국어 Sign in Articles Modern Web Guidance is now stable! Upgrade your coding agents with expert-vetted web development best practices.
Read the announcement . Home Articles Resources Fast load times Performance monitoring with Lighthouse CI Stay organized with collections Save and categorize content based on your preferences. How to add Lighthouse to a continuous integration system, such as GitHub Actions. Katie Hempenius Lighthouse CI is a suite of tools for using Lighthouse during continuous integration. Lighthouse CI can be incorporated into developer workflows in many different ways.
This guide covers the following topics: Using the Lighthouse CI CLI. Configuring your CI provider to run Lighthouse CI. Setting up a GitHub Action and status check for Lighthouse CI. This will automatically display Lighthouse results on GitHub pull requests. Building a performance dashboard and data store for Lighthouse reports. Overview Lighthouse CI is a suite of free tools that facilitate using Lighthouse for performance monitoring.
A single Lighthouse report provides a snapshot of a web page's performance at the time that it is run; Lighthouse CI shows how these findings have changed over time. This can be used to identify the impact of particular code changes or ensure that performance thresholds are met during continuous integration processes. Although performance monitoring is the most common use case for Lighthouse CI, it can be used to monitor other aspects of the Lighthouse report - for example, SEO or accessibility.
The core functionality of Lighthouse CI is provided by the Lighthouse CI command line interface. (Note: This is a separate tool than the Lighthouse CLI .) The Lighthouse CI CLI provides a set of commands for using Lighthouse CI. For example, the autorun command executes multiple Lighthouse runs, identifies the median Lighthouse report, and uploads the report for storage. This behavior can be heavily customized by passing additional flags or customizing Lighthouse CI's configuration file, lighthouserc.js .
Although the core functionality of Lighthouse CI is primarily encapsulated in the Lighthouse CI CLI, Lighthouse CI is typically used through one of the following approaches: Running Lighthouse CI as part of continuous integration Using a Lighthouse CI GitHub Action that runs and comments on every pull request Tracking performance over time via the dashboard provided by Lighthouse Server. All of these approaches are built upon the Lighthouse CI CLI.
Alternatives to Lighthouse CI include third-party performance monitoring services or writing your own script to collect performance data during the CI process. You should consider using a third-party service if you'd prefer to let someone else handle the management of your performance monitoring server and test devices, or, if you want notification capabilities (such as email or Slack integration) without having to build these features yourself.
Use Lighthouse CI locally This section explains how to run and install the Lighthouse CI CLI locally and how to configure lighthouserc.js . Running the Lighthouse CI CLI locally is the easiest way to make sure that your lighthouserc.js is configured correctly. Install the Lighthouse CI CLI. npm install -g @lhci/cli Lighthouse CI is configured by placing a lighthouserc.js file in the root of your project's repo. This file is mandatory and will contain Lighthouse CI related configuration information.
Although Lighthouse CI can be configured to be used without a git repo , the instructions in this article assume that your project repo is configured to use git. In the root of your repository, create a lighthouserc.js configuration file . touch lighthouserc.js Add the following code to lighthouserc.js . This code is an empty Lighthouse CI configuration. You will be adding to this configuration in later steps. module . exports = { ci : { collect : { /* Add configuration here */ }, upload : { /* Add configuration here */ }, }, }; Every time that Lighthouse CI runs, it starts a server to serve your site.
This server is what enables Lighthouse to load your site even when no other servers are running. When Lighthouse CI finishes running, it will automatically shutdown the server. To ensure that serving works correctly, you should configure either the staticDistDir or startServerCommand properties. If your site is static, add the staticDistDir property to the ci.collect object to indicate where your static files are located.
Lighthouse CI will use its own server to serve these files while testing your site. If your site is not static, add the startServerCommand property to the ci.collect object to indicate the command that starts your server. Lighthouse CI will start a new server process during testing and shut it down after. // Static site example collect : { staticDistDir : './public' , } // Dynamic site example collect : { startServerCommand : 'npm run start' , } Add the url property to the ci.collect object to indicate URL(s) that Lighthouse CI should run Lighthouse against.
The value of the url property should be provided as an array of URLs; this array can contain one or more URLs. By default, Lighthouse CI will run Lighthouse three times against each URL. collect : { // ... url : [ 'http://localhost:8080' ] } Add the target property to the ci.upload object and set the value to 'temporary-public-storage' . The Lighthouse report(s) collected by Lighthouse CI will be uploaded to temporary public storage.
The report will remain there for seven days and then be automatically deleted. This setup guide uses the "temporary public storage" upload option because it is quick to setup. For information on other ways of storing Lighthouse reports, refer to the documentation . upload : { target : 'temporary-public-storage' , } The storage location of the report will be similar to this: https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html (This URL won't work because the report has already been deleted.) Run the Lighthouse CI CLI from the terminal using the autorun command.
This will run Lighthouse three times and upload the median Lighthouse report. lhci autorun If you've correctly configured Lighthouse CI, running this command should produce output similar to this: ✅ .lighthouseci/ directory writable ✅ Configuration file found ✅ Chrome installation found ⚠️ GitHub token not set Healthcheck passed! Started a web server on port 65324 ... Running Lighthouse 3 time ( s ) on http://localhost:65324/index.html Run #1...done.
Run #2...done. Run #3...done. Done running Lighthouse! Uploading median LHR of http://localhost:65324/index.html...success! Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591720514021-82403.report.html No GitHub token set, skipping GitHub status check. Done running autorun. You can ignore the GitHub token not set message in the console output. A GitHub token is only necessary if you want to use Lighthouse CI with a GitHub Action.
How to setup a GitHub Action is explained later in this article. Clicking on the link in the output that begins with https://storage.googleapis.com... will take you to the Lighthouse report corresponding to the median Lighthouse run. The defaults used by autorun can be overridden via the command line or lighthouserc.js . For example, the lighthouserc.js configuration below indicates that five Lighthouse runs should be collected every time autorun executes.
Update lighthouserc.js to use the numberOfRuns property: module . exports = { // ... collect : { numberOfRuns : 5 }, // ... }, }; Re-run the autorun command: lhci a
The rest of this page is on the live site.