DOCSEARCHbyAlgolia
Submit Docs

Lighthouse CI

repository·main·Indexed 27 days ago

https://github.com/googlechrome/lighthouse-ci

A suite of tools for continuously running, saving, retrieving, and asserting against Lighthouse audits to prevent performance and accessibility regressions in CI/CD pipelines. The ecosystem includes @lhci/cli for running audits, @lhci/server for visualizing results, @lhci/viewer for report comparison, and @lhci/utils for shared logic. It supports various deployment methods including Docker, Google Cloud Kubernetes (GKE), and Heroku.

Tokens
22.1K
Snippets
53
Records
115
Agent score
91%

What's inside lighthouse-ci

  2. Overview of Lighthouse CI features

    main

    Lighthouse CI is a suite of tools designed to automate running, saving, retrieving, and asserting against Lighthouse results. Key capabilities include:

    • PR Integration: Receive Lighthouse reports alongside every Pull Request.
    • Regression Prevention: Protect accessibility, SEO, offline support, and performance best practices.
    • Metric Tracking: Monitor performance metrics and Lighthouse scores over time.
    • Performance Budgets: Set and maintain budgets for scripts and images.
    • Variance Reduction: Run Lighthouse multiple times to ensure stable results.
    • Resource Comparison: Compare two versions of a site to identify improvements or regressions in specific resources.

  3. Understand the Lighthouse CI architecture and core packages

    main

    Lighthouse CI is composed of two primary packages:

    1. @lhci/cli: The primary interface for users. It contains the commands used to run audits, assert results, and manage data.
    2. @lhci/server: Used to set up and run the Lighthouse CI server for storing and viewing results.

    Commands are categorized by where they are intended to be executed.

  4. Understand LHCI Server Security Model

    main

    By default, the LHCI server has a weak security model where anyone with HTTP access can view and create data. It uses two built-in tokens for specific permissions:

    • Build Token: Allows uploading new data to a project. It does not allow editing or deleting historical data. This can be treated as public knowledge for open-source projects.
    • Admin Token: Allows editing or deleting data within a project. This should never be shared with untrusted users or placed in CI environments, as it can be used to delete entire projects.

    If you lose these tokens, you can reset them by connecting directly to the server's storage and using the lhci wizard command.

  7. Understand the Lighthouse CI versioning policy

    main

    Lighthouse CI (LHCI) follows semantic versioning (semver) on the 0.x.x track. While breaking changes are generally not introduced in patch versions (except for critical security or stability patches), the project's definition of a breaking change is stricter than core Lighthouse.

    To identify breaking changes in updates, look for the BREAKING CHANGE: brief description of the break marker in commit logs or check the release notes of the upcoming release.

  9. Identify appropriate Lighthouse CI commands for your environment

    main

    Depending on whether you are running tasks locally, on a CI server, or interacting with the LHCI server, you should use different commands:

    Local Execution (User Device)

    • wizard: Create new projects on the LHCI server.
    • collect: Run Lighthouse audits multiple times.
    • open: Open the median run results.

    Remote Execution (CI Servers)

    • autorun: Automated execution flow.
    • healthcheck: Verify environment readiness.
    • collect: Run Lighthouse audits.
    • assert: Evaluate audit results against assertions.
    • upload: Send reports and assertion results to a storage service or server.

    LHCI Server Execution

    • server: Run the LHCI server.
    • wizard: Reset tokens.

  10. Install and run LHCI Server

    main

    To run the LHCI server on your own infrastructure, you need Node v16 LTS and a database (sqlite, mysql, or postgresql). You can install the necessary dependencies via npm and start the server using the @lhci/server package or the lhci CLI.

    To run locally via the CLI with SQLite:

    npm install -D @lhci/cli @lhci/server sqlite3
npx lhci server --storage.storageMethod=sql --storage.sqlDialect=sqlite --storage.sqlDatabasePath=./db.sql

  11. Deploy LHCI Server to Google Cloud Kubernetes (GKE)

    main

    You can deploy the LHCI server to Google Cloud Platform using GKE. This method uses Kubernetes manifests to set up data claims, deployments, and services.

    Prerequisites

    • A Google Cloud Project ID.
    • A target GCP Zone.
    • gcloud and kubectl installed and configured.

    Deployment Steps

    1. Configure gcloud: Set your project and compute zone.
    2. Create Cluster: Create a Kubernetes cluster named lhci-cluster with 1 node.
    3. Apply Manifests: Download and apply the lhci-data-claim.yml, lhci-deployment.yml, and lhci-service.yml files.
    4. Retrieve URL: Run kubectl get service to find the EXTERNAL-IP. This IP is your LHCI_SERVER_BASE_URL.

    Warning: GCP pricing for Kubernetes clusters beyond the first one may incur costs (approx. $72/month as of June 2020). For more economical options, consider the Heroku guide.

    # Configure the gcloud utility
PROJECT_ID="<your GCP project id here>"
COMPUTE_ZONE="<your zone here, e.g. us-central1-a>"
gcloud config set project "$PROJECT_ID"
gcloud config set compute/zone "$COMPUTE_ZONE"

# Create our Kubernetes cluster for LHCI
gcloud container clusters create lhci-cluster --num-nodes=1

# Deploy the LHCI server
curl -O https://raw.githubusercontent.com/GoogleChrome/lighthouse-ci/main/docs/recipes/docker-server/kubernetes/lhci-data-claim.yml
curl -O https://raw.githubusercontent.com/GoogleChrome/lighthouse-ci/main/docs/recipes/docker-server/kubernetes/lhci-deployment.yml
curl -O https://raw.githubusercontent.com/GoogleChrome/lighthouse-ci/main/docs/recipes/docker-server/kubernetes/lhci-service.yml
kubectl apply -f ./lhci-data-claim.yml
kubectl apply -f ./lhci-deployment.yml
kubectl apply -f ./lhci-service.yml

# Verify deployment and get the EXTERNAL-IP
kubectl get deployment
kubectl get service

  12. Configure Lighthouse CI using recommended patterns

    main

    Depending on your experience level, you can choose different configuration strategies:

    Easy Mode

    Recommended for beginners. Only configure upload to manually monitor scores.

    Next Level

    Recommended for those familiar with Lighthouse. Use assert with a preset (e.g., lighthouse:recommended) and disable specific audits you are currently failing using the assertions object.

    The Complete Experience

    Recommended for seasoned users. Use collect to increase numberOfRuns, assert to set specific metric budgets (e.g., first-contentful-paint), and upload to send results to a Lighthouse CI server.

    // Easy Mode
{
  "ci": {
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

// Next Level
{
  "ci": {
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "offscreen-images": "off",
        "uses-webp-images": "off",
        "color-contrast": "off"
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

// The Complete Experience
{
  "ci": {
    "collect": {
      "numberOfRuns": 5
    },
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "first-contentful-paint": [
          "error",
          {"maxNumericValue": 2000, "aggregationMethod": "optimistic"}
        ],
        "interactive": ["error", {"maxNumericValue": 5000, "aggregationMethod": "optimistic"}]
      }
    },
    "upload": {
      "target": "lhci",
      "serverBaseUrl": "https://lhci.example.com"
    }
  }
}