Running Lighthouse CI Server Locally

I had previously set up Lighthouse CI with Github Actions, but I still found myself looking longingly at the reports provided by Lighthouse CI Server as a way to compare results over time. While the docs are mainly focused on running on a public server with persistent storage (which is clearly the most useful way to do this,) I couldn’t help but wonder if I could run the server locally to capture some quick data comparing a few specific changes. Turns out you absolutely can. The docs provide an example Docker container to use locally, but I went with the even lower-fi solution.

From within the repository containing the code that I’m measuring, I added packages for Lighthouse CI Server, along with sqlite for data storage.

npm install -D @lhci/cli @lhci/server sqlite3

I also added Concurrently as it made it easier to start the server and collect data in one fell swoop:

npm install -D concurrently

While I was messing around with package.json I added the following scripts:

"scripts": {
  "lhci:audit": "concurrently \"npm run lhci:server\" \"lhci autorun\"",
  "lhci:wizard": "lhci wizard",
  "lhci:server": "lhci server --storage.storageMethod=sql --storage.sqlDialect=sqlite --storage.sqlDatabasePath=./db.sql"

With those scripts in place, I can start the server by running:

npm run lhci:server

And then run the wizard with:

npm run lhci:wizard

The wizard will ask you a few questions about your server and your code repository, and then provide your build token and admin token. With that information in hand, I added lighthouserc.js in the root of my repository containing the following:

module.exports = {
  ci: {
    collect: {
      url: [''],
    upload: {
      target: 'lhci',
      serverBaseUrl: 'http://localhost:9001',
      token: '###-###-###', // the build token provider by the wizard. Could also use LHCI_TOKEN variable instead

In my case, I added lighthouserc.js to the .gitignore for my project because I didn’t want these local settings to override the Lighthouse settings I already had working with Github Actions. You may also want to ignore .lighthouseci/ and db.sql as well if you are only planning to store this information locally.

With that in place I can now run

npm run lhci:audit

which will start the Lighthouse CI Server and record results for the current commit. If I run this repeatedly as commits are made, I can get a granular comparison of the impact of my changes.

Example lighthouse checks

This would certainly be more useful incorporated into your main CI process, but this local approach can still be useful for benchmarking a feature branch or making some other small scale measurement.