Lighthouse CI Beginner's Guide

Lighthouse CI Beginner's Guide

A quick and easy Lighthouse CI workflow


We are all familiar with Lighthouse, the open-source, automated tool for better quality web pages. It checks our website and reports website metrics like performance, accessibility, website best practices, SEO, and more, hence, giving us a holistic view of our site. A rubric, if you will.

However, going through each page and checking its Lighthouse score can be a pain, a mundane task prone to human errors. Imagine if you could automate it, giving you reports of all of your pages, as you make your changes. Now stop imagining, because it already exists in Lighthouse CI.

End Result

Screenshot 2022-04-18 at 5.52.47 PM.png

Screenshot 2022-04-18 at 5.53.12 PM.png

We’re putting this here, so you know what you’ll get by the end of this post. You’ll have a CI workflow in your GitHub Repository that lists Lighthouse Tests and how good your page(s) did. This information will let you know whether you’re on the right track. No more wasting time by manually running tests to see how you did. Let your CI workflow handle that for you while you sip your refreshing coffee.

The Plan

Here’s how to proceed:

  • Install Lighthouse CI (LHCI)
  • Configure LHCI
  • It is CI Time!

Install Lighthouse CI (LHCI)

Start by installing Lighthouse CI. There are two components you need: @lhci/cli, which runs the tests, and @lhci/server, which runs the server-related code. You can this locally to avoid the need for any external setup.

I’m using yarn in this example, but you can use whatever package manager is in your current project. You can start by running yarn global add @lhci/cli. Normally, you can install packages locally, but LHCI needs to run a binary, so you have to install it globally. Once it’s done, you can run yarn add @lhci/server, which will install the server-related packages locally.

Configure LHCI

LHCI has many configuration options but let’s start simple. Create a lighthouserc.js file at the root of your directory. Here’s an example of what it should look like.

module.exports = {
  ci: {
    collect: {
      url: ["<http://localhost:3000/>"],
      startServerCommand: "yarn build && yarn start",
    upload: {
      target: "temporary-public-storage",
    assert: {
      preset: "lighthouse:recommended",

Let’s break this down a little bit.

collect: You ask Lighthouse to test a particular URL and what commands to run to get the server up and running so it can visit our pages.

upload: You ask Lighthouse to create the reports and temporarily host them somewhere, so you can later have a look.

assert: Here, you can choose some test suites for Lighthouse. For now, let’s go with lighthouse:recommended. You can fine-tune assertions too by choosing individual metrics for a completely custom test suite.

And that’s it! You’ve set up your Lighthouse configuration. There’s only one more step left.

It Is CI Time!

In case you’re not familiar, Continuous Integration (CI) allows you to set up jobs that run on certain triggers. These jobs allow you to automate various tasks, one of which is generating Lighthouse reports. We’re using GitHub Actions for this post, but the underlying principle is similar across CI tools.

So head over to .github/workflows in your Project and create a lighthouse.yml file. If the directory is not already present, create it. Here’s an example of what it looks like.

name: Lighthouse CI
on: [pull_request, workflow_dispatch]

    name: Lighthouse
    runs-on: ubuntu-latest
      - name: Checkout Code
      uses: actions/checkout@v2
      - name: Use Node.js
      uses: actions/setup-node@v2
        node-version: lts/gallium
        cache: yarn
        cache-dependency-path: lhci/yarn.lock
      - name: run Lighthouse CI
        run: |
          cd lhci
          yarn global add @lhci/cli@0.9.0
          lhci autorun --config=./lighthouserc.js

Here’s what this file does.

  1. It checks out the code from the repository (current branch by default)
  2. It sets up Node.js for you
  3. It adds all of your dependencies, adds LHCI globally and runs the tests.

That’s it! A simple but powerful file.

Putting it all together

Now that you have everything you need, let’s see how this works. Let’s say you’re working on a feature branch and you want to push some code changes. You push them to your repo and thing usually end there.

Lighthouse CI Example.png

However, now you’ll see some tasks listed in your PR. These are the CI tasks you just set up. If this is all you have, you’ll see just one task, but projects can have multiple tasks running together. If you click on it, it will show you the logs. You can see the Lighthouse tests running here, with all your scores! Hooray! This can take a few minutes, but it happens on it’s own, allowing you to get on with another task, or even take a break. You deserve it. :)


Lighthouse is an amazing tool that got cooler with Lighthouse CI. It allows you to run automated Lighthouse tests with each push of your code. With a slew of options on how to make it tick, you can decide what you want Lighthouse to do for you. Setting it up is fairly quick, so it’s very little effort for maximum benefit.