Lighthouse CI: Catch Performance Regressions Before They Ship

Lighthouse CI solves a specific problem: you fix performance issues, merge the PR, then someone adds a 500KB image next week and performance tanks again.

Lighthouse CI is a command-line tool that runs Google Lighthouse audits in your CI pipeline. It tests your site against performance budgets and fails the build if metrics drop below thresholds.

Installation

1
npm install -g @lhci/cli@latest

Create lighthouserc.json in your project root. I’m using Astro, so the default port is 4321:

1
{
2
  "ci": {
3
    "collect": {
4
      "url": [
5
        "http://localhost:4321/",
6
        "http://localhost:4321/blog"
7
      ],
8
      "numberOfRuns": 3
9
    },
10
    "assert": {
11
      "assertions": {
12
        "categories:performance": ["error", {"minScore": 0.9}],
13
        "first-contentful-paint": ["error", {"maxNumericValue": 2000}],
14
        "largest-contentful-paint": ["error", {"maxNumericValue": 2500}],
15
        "cumulative-layout-shift": ["error", {"maxNumericValue": 0.1}]
16
      }
17
    }
18
  }
19
}

Running Locally First

Start by running Lighthouse CI locally. This lets you set realistic performance budgets before adding it to your pipeline.

1
npm run dev
2
lhci autorun

The autorun command runs three audits per URL, takes the median scores, and checks them against your assertions. When audits fail, you’ll see exactly which metrics are over budget.

This is where you tune your configuration. If your site consistently scores 0.85 on performance but you set minScore: 0.9, every build fails. Run locally, see what scores you actually get, then set budgets slightly above your current performance. The goal is to prevent regressions, not to fail every build.

For static sites, point directly to your build output:

1
{
2
  "ci": {
3
    "collect": {
4
      "staticDistDir": "./dist"
5
    }
6
  }
7
}

For apps that need a running server, tell Lighthouse CI how to start it:

1
{
2
  "ci": {
3
    "collect": {
4
      "url": ["http://localhost:3000/"],
5
      "startServerCommand": "npm run preview"
6
    }
7
  }
8
}

Once your assertions pass locally, add Lighthouse CI to your pipeline.

Framework-Specific Setup

Next.js:

Next.js uses port 3000 by default. Your configuration needs npm run build to generate the production build, then npm start to serve it:

1
{
2
  "ci": {
3
    "collect": {
4
      "url": ["http://localhost:3000/"],
5
      "startServerCommand": "npm run build && npm start"
6
    }
7
  }
8
}

For static exports (output: 'export' in next.config.js), use staticDistDir:

1
{
2
  "ci": {
3
    "collect": {
4
      "staticDistDir": "./out"
5
    }
6
  }
7
}

Nuxt:

Nuxt uses port 3000 by default. Build with npm run build, then preview with npm run preview (which uses nuxi preview internally):

1
{
2
  "ci": {
3
    "collect": {
4
      "url": ["http://localhost:3000/"],
5
      "startServerCommand": "npm run build && npm run preview"
6
    }
7
  }
8
}

For static generation (nuxi generate), point to the output directory:

1
{
2
  "ci": {
3
    "collect": {
4
      "staticDistDir": "./.output/public"
5
    }
6
  }
7
}

Adding to CI

GitHub Actions (.github/workflows/lighthouse.yml):

1
name: Lighthouse CI
2
on: [pull_request]
3

4
jobs:
5
  lighthouse:
6
    runs-on: ubuntu-latest
7
    steps:
8
      - uses: actions/checkout@v4
9
      - uses: actions/setup-node@v4
10
        with:
11
          node-version: '20'
12

13
      - name: Install dependencies
14
        run: npm ci
15

16
      - name: Build site
17
        run: npm run build
18

19
      - name: Serve site
20
        run: npm run preview &
21

22
      - name: Wait for server
23
        run: npx wait-on http://localhost:4321
24

25
      - name: Run Lighthouse CI
26
        run: |
27
          npm install -g @lhci/cli@latest
28
          lhci autorun

GitLab CI (.gitlab-ci.yml):

1
lighthouse:
2
  image: cypress/browsers:node16.17.0-chrome106
3
  script:
4
    - npm ci
5
    - npm run build
6
    - npm run preview &
7
    - npx wait-on http://localhost:4321
8
    - npm install -g @lhci/cli@latest
9
    - lhci autorun
10
  only:
11
    - merge_requests

Performance Budgets

The assertions block defines what passes and what fails.

Score-based budgets:

1
"categories:performance": ["error", {"minScore": 0.9}]

Performance score must be 90 or above. Lighthouse scores range from 0 to 1.

Metric-based budgets:

1
"first-contentful-paint": ["error", {"maxNumericValue": 2000}]

First Contentful Paint must be under 2000ms. This is more reliable than scores because it tests actual render timing.

Disabling audits:

1
"uses-responsive-images": "off",
2
"offscreen-images": "off"

Turn off audits that don’t apply to your use case. Responsive image warnings are often false positives for modern image formats.

What Happens When It Fails

1
Checking assertions against 2 URL(s), 3 run(s) each.
2

3
✘ http://localhost:4321/
4

5
  categories:performance failure for minScore assertion
6
       expected: >= 0.9
7
          found: 0.87
8

9
  largest-contentful-paint failure for maxNumericValue assertion
10
       expected: <= 2500
11
          found: 3200
12

13
Assertion failed. Exiting with status code 1.

The build fails. Fix the performance issue, push again, repeat.

Running Lighthouse CI with Desktop Settings

Lighthouse CI runs mobile audits by default. Mobile simulates a slower device with 4x CPU slowdown and slow 3G network conditions. For desktop testing, configure the preset in your settings:

1
{
2
  "ci": {
3
    "collect": {
4
      "settings": {
5
        "preset": "desktop"
6
      }
7
    }
8
  }
9
}

Desktop audits use faster throttling and no CPU slowdown. Test the device type your users actually use.

Storage Options

1
"upload": {
2
  "target": "temporary-public-storage"
3
}

This stores reports at https://googlechrome.github.io/lighthouse-ci/viewer/ for 7 days. The URL appears in CI logs.

For permanent storage, use the Lighthouse CI Server or store results as build artifacts.

When It’s Most Valuable

Lighthouse CI catches regressions that code review misses. A developer adds moment.js (231KB). Code looks fine. CI fails because First Contentful Paint jumped from 1.8s to 3.2s.

Without CI, that ships to production. With CI, you catch it in the PR and suggest date-fns (13KB) instead.

It works best for content sites, marketing pages, and documentation. It’s less useful for dashboards and apps where performance varies based on data.