How to configure a Web Performance Budget with Lighthouse CI

Hey folks, it's me again! :)

Today, I would like to share with you how you can use Lighthouse CI to audit various software qualities of your project in Continous Integration but also how you can set up a Web Performance Budget strategy to not ship unintentional regressions.

I used this techique in various kinds of projects and I really liked the outcome of it.

Enjoy!

Problem

In Software Development, we always aimed to develop and ship fast. Nowadays with the growing popularity of AI agents that help us ship code even faster, being able to set certain quality guardrails (i.e. in Continous Integration/Continous Deployment) is essential to maintain software quality.

This is especially visible in the area of Web Performance where we can very easily ship performance regressions by adding a third party script, an unoptimized image or multiple custom fonts.

To maintain good performance and exceptional user experience, we need to find a way to warn us early about unexpected regressions. This is where Lighthouse CI can help us.

Solution

Lighthouse CI is a tool that can be used both in local development as well (and primarily) in the CI GitHub Action. The idea is simple:

1. Define a configuration file
2. Add a GitHub action/step
3. See results and react to them before they reach production

The basic example could just be like following:

name: CI
on: [push]
jobs:
  lighthouseci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install && npm install -g @lhci/[email protected]
      - run: npm run build
      - run: lhci autorun

But this will run the test in a basic setup - in our case we want to add some more configuration that will allow us to define our custom budget, and update it on the go to more restrict setup after time.

ci:
  collect:
    numberOfRuns: 5
    startServerCommand: rails server -e production
    url:
      - http://localhost:3000/
      - http://localhost:3000/pricing
      - http://localhost:3000/support
  assert:
    preset: lighthouse:recommended
    assertions:
      first-contentful-paint:
        - error
        - maxNumericValue: 2000
          aggregationMethod: optimistic
      largest-contentful-paint:
        - error
        - maxNumericValue: 2500
          aggregationMethod: optimistic
      cumulative-layout-shift:
        - error
        - maxNumericValue: 100
          aggregationMethod: optimistic
  upload:
    target: lhci
    serverBaseUrl: https://lhci.example.com

This configuration can either be in the yaml,js,json or any other supported format. What is important is that with it, you can be warned early about unexpected regressions and update the budget later to match your needs and goals better.

And if you would like to compare one LHCI result to the previous one to show instant improvements/regressions, here is a great example for that https://github.com/adevinta/actions-lighthouseci-compare

Learn more

Here is the recording of my talk at JS Poland conference where I was talking about this topic (and also a bit about Playwright and Accessibility):