npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@spotify/lighthouse-audit-service

v2.0.0

Published

Run, store, and view Lighthouse audits on all of your websites

Downloads

244

Readme

Lighthouse Audit Service

Actions Status Version

A service meant to help you run, schedule, store, and monitor Lighthouse reports over time. The API is built with Backstage in mind, but can be used without!

Usage

With Docker

The simplest way to deploy the app is with our image on Docker Hub.

docker run spotify/lighthouse-audit-service:latest

Be sure to see "Configuring Postgres" - you will likely need to configure the Postgres credentials, even when trying the app out locally. A list of supported environment variables:

With Docker Compose

A simple way to trial this tool is with the following docker compose file which spins up a postgres container and connects it with the lighthouse image. This would not be a great way to run this in a production environment, but a fast way to test out this tool and see if it meets your needs.

# docker-compose.yml
version: '3.1'

services:

  db:
    image: postgres:latest
    restart: always
    environment:
      POSTGRES_USER: dbuser
      POSTGRES_PASSWORD: example
  
  lighthouse:
    image: spotify/lighthouse-audit-service:latest
    environment:
      PGHOST: db
      PGUSER: dbuser
      PGPASSWORD: example
      LAS_PORT: 4008
    ports:
      - "4008:4008"

As an npm package

Install the project:

yarn add @spotify/lighthouse-audit-service

Then, you may either start up the server as a standalone process:

import { startServer } from '@spotify/lighthouse-audit-service';

startServer({
  port: 8080,
  cors: true,
  postgresConfig: {
    db: 'postgres',
    database: 'mydb',
    password: 'secretpassword',
    port: 3211,
  },
});

As an express app

You may nest the express app that the lighthouse-audit-service exposes inside of another express app as a subapp by using getApp and app.use():

import express from 'express';
import { getApp as getLighthouseAuditServerApp } from '@spotify/lighthouse-audit-service';

async function startup() {
  const app = express();
  const lighthouseServer = await getLighthouseAuditServerApp();

  app.use('/lighthouse', lighthouseServer);

  const server = app.listen(4000, () => {
    console.log(
      'listening on 4000 - http://localhost:4000/lighthouse/v1/websites',
    );
  });

  // be sure to `.get()` the connection and end it as you close your custom server.
  server.on('close', () => {
    lighthouseServer.get('connection').end();
  });
}

startup();

Configuring Postgres

You will need a Postgres database for lighthouse-audit-service to use to manage the stored audits. The database will be configured on app startup, so you need only initialize an empty database and provide credentials to lighthouse-audit-service.

You can set the Postgres credentials up either by setting environment variables, which will be interpreted by pg:

PGUSER=dbuser \
PGHOST=database.server.com \
PGPASSWORD=secretpassword \
PGDATABASE=mydb \
PGPORT=3211 yarn start

..or, by passing the config in programmatically as postgresConfig:

import { startServer } from '@spotify/lighthouse-audit-service';

startServer({
  port: 8080,
  cors: true,
  postgresConfig: {
    database: 'mydb',
    host: 'my.db.host',
    user: 'dbuser',
    password: 'secretpassword',
    port: 3211,
  },
});

Both startServer and getApp support this. Further, both of these methods support optionally passing a pg client as an optional second argument.

import { Pool } from 'pg';
const conn = new Pool();
startServer({}, conn);

API

We offer a REST API, as well as some programmatic ways, to interact with lighthouse-audits-service.

REST

We are currently seeking contributions on documenting the API in a sustainable way (aka with Swagger/OpenAPI, preferably generated). For now, the REST API includes:

Audit routes

  • GET /v1/audits - list of all audits run
  • GET /v1/audits/:auditId - get an audit, either as HTML or JSON depending on the Accept header of the request.
  • POST /v1/audits - trigger a new audit
    • expected JSON payload:
      • url: string - url to audit
      • options - all optional
        • awaitAuditCompleted: boolean - makes awaiting triggerAudit wait until the audit has completed. By default, the audit runs in the background.
        • upTimeout: number - time in ms to wait for your site to be up (default 30000). We test that your URL is reachable before triggering Lighthouse (useful if this Lighthouse test will run for an ephemeral URL).
        • chromePort: number - chrome port for puppeteer to use
        • chromePath: string - chrome path for puppeteer to use
        • lighthouseConfig: LighthouseConfig - custom Lighthouse config to be used when running the audit.
  • DELETE /v1/audits/:auditId - delete an audit

Website routes

  • GET /v1/websites - list of audits grouped by url
  • GET /v1/websites/:websiteUrl - get the audits associated with this url. be sure to uri encode that url!
  • GET /v1/audits/:auditId/website - get the group of audits associated with the url used for this audit.

Programatic

All of the API methods exposed on REST are also exposed programmatically.

Server

  • startServer(options?, conn?) - start REST server
  • getApp(options?, conn?) - return express app, ready to be started

Audit methods

  • getAudits(conn, listOptions?) - list of all audits run
    • listOptions (all optional):
      • limit and offset for pagination
      • where: SQLStatement - using sql-template-strings, create a custom WHERE to inject into the query.
  • getAudit(conn, auditId) - retrieve an Audit by id.
  • triggerAudit(conn, url, options?) - trigger a new audit.
    • options (all optional):
      • awaitAuditCompleted: boolean - makes awaiting triggerAudit wait until the audit has completed. By default, the audit runs in the background.
      • upTimeout: number - time in ms to wait for your site to be up (default 30000). We test that your URL is reachable before triggering Lighthouse (useful if this Lighthouse test will run for an ephemeral URL).
      • chromePort: number - chrome port for puppeteer to use
      • chromePath: string - chrome path for puppeteer to use
      • lighthouseConfig: LighthouseConfig - custom Lighthouse config to be used when running the audit.
  • deleteAudit(conn, auditId) - delete an Audit from the DB.
  • Audit - class used by the Audit API.
    • properties:
      • url: string: the original url when the audit was requested
      • status: string: the status of the audit; COMPLETED, FAILED, or RUNNING
      • timeCreated: string: ISO-8601 time when the audit was created
      • timeCompleted: string?: nullable ISO 8601 time when the audit was completed, if it has completed
      • report: LHR?: nullable LHR object which contains the full Lighthouse audit.
      • categories: LHRCategories: nullable map of categories, stripped down to only include the scores. useful for lists of audits, when trying to keep the payload to a reasonable size.

Website methods

  • getWebsites(conn, listOptions?) - list of audits grouped by url
    • listOptions (all optional):
      • limit and offset for pagination
      • where: SQLStatement - using sql-template-strings, create a custom WHERE to inject into the query.
  • getWebsiteByAuditId(conn, auditId) - get Website associated with this audit.
  • getWebsiteByUrl() - get Website associated with this url.
  • Website - class used by the Website API.
    • properties:
      • url: string: the audited url
      • audits: Audit[]: list of Audits for that URL.

Contributing

This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.

Publish should occur on merge using web-scripts and semantic-release. Please use conventional commits to signal what the new version should be.

External contributions and issues are welcome!

License

Copyright 2020 Spotify AB.

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0