Roadie’s Blog

How to use the Backstage Lighthouse plugin

By David TuiteMay 23rd, 2020
How to use the Backstage Lighthouse plugin

Lighthouse is an open-source, automated tool for improving the quality of web pages. You give it the URL of a web page, it loads the page and runs tests to check the page’s quality.

You can use it via the PageSpeed Insights website. Simply enter a URL in the box, hit Analyze, and a few seconds later you will have a quality score for the website behind the URL, information about how long the page took to load and some suggestions about what to do better.

A site being tested in PageSpeed insights

You can also use Lighthouse via the Chrome DevTools, the command line and as a NodeJS module.

» npm install -g lighthouse
» lighthouse

Lighthouse with Backstage

In your company, there may be many teams making websites for different purposes. It is useful to track the quality of these websites over time to ensure that code changes are not hurting performance or accessibility.

If customers complain that your website is slow, it can be helpful to look back over Lighthouse results to figure out if and when the performance drop occurred. You can then look at commits around this time to pinpoint the cause of the slowness.

Backstage has a Lighthouse plugin available which makes it easy to run tests against the websites your company produces.

The audit view of a site in the Lighthouse plugin

You can track the results of Lighthouse tests over time to see if your site is performing better or worse as you make changes.

Sites trending over time in the plugin

Running Lighthouse with Backstage

To use Lighthouse with Backstage, you need three things:

  1. A Backstage instance you can run locally with the Lighthouse Plugin installed.
  2. A running Lighthouse microservice which actually executes the Lighthouse tests before sending the results back to the plugin.
  3. A PostgreSQL database for the Lighthouse microservice to talk to.

Let’s set them up in reverse order.


Assuming you already have posgresql installed and running, you can easily create a database for Lighthouse with the following command. The database this creates will have no password but it’s fine for local development.

» createdb -O [username] -U [username] -w lighthouse_audit_service

You can verify this database by logging into it with psql.

» psql -h localhost -p 5432 -U [username] -d lighthouse_audit_service
psql (11.5)
Type "help" for help.



Lighthouse microservice

We’re going to run the Lighthouse microservice with docker. We’ll have to pass a few environment variables to our Docker run command. The easiest way to do this is by putting them in a file.

Create a file called development.env with the following variables.

  • LAS_PORT tells the Lighthouse microservice which port to expose to incoming HTTP requests. It’s important that this port matches the one defined in the Backstage Lighthouse plugin. Otherwise the plugin will never receive a response to its Lighthouse testing requests.
  • PGHOST is important because our Lighthouse microservice is running inside Docker but our PG database is exposing a port on localhost. We have to use a special Docker DNS name to allow this.

With that file defined, we should now be able to run the Lighthouse microservice like this:

» docker run -p 3003:3003 -p 5432:5432 --env-file development.env spotify/lighthouse-audit-service:latest                                              130yarn run v1.22.0
$ node ./cjs/run.js
info: building express app... {"service":"lighthouse-audit-service","timestamp":"2020-05-23T19:03:00.202Z"}
info: running db migrations... {"service":"lighthouse-audit-service","timestamp":"2020-05-23T19:03:00.290Z"}
info: listening on port 3003 {"service":"lighthouse-audit-service","timestamp":"2020-05-23T19:03:00.320Z"}

It might take a few seconds to start up when you run it for the first time because it will have to download the Docker container from the internet. When it starts, it automatically runs some database migrations to prepare your database.

Backstage with the Lighthouse Plugin

Luckily for us, Backstage comes with the Lighthouse Plugin installed and enabled so it’s easy to try it out.

Follow the Getting Started Guide to get Backstage installed.

If you open packages/app/src/plugins.ts in your favorite code editor you should see that the Lighthouse plugin is already installed.

export { plugin as LighthousePlugin } from '@backstage/plugin-lighthouse';

In packages/app/src/apis.ts you should see that the Lighthouse plugin is configured to send requests to port 3003.

builder.add(lighthouseApiRef, new LighthouseRestApi('http://localhost:3003'));

Now, run Backstage with yarn start and visit http://localhost:3000/lighthouse and you should see the Backstage Lighthouse interface.

A successful audit in Backstage

Awesome! If you run an audit a few times on the same website you can see the trend over time. Perfect for ensuring that your websites are staying responsive and accessible.

Become a Backstage expert

To get the latest news, deep dives into Backstage features, and a roundup of recent open-source action, sign up for Roadie's Backstage Weekly. See recent editions.

We will never sell or share your email address.