Integrations

CI/CD Integration

Last updated by
Harlan Wilton
in chore: lint markdown.

Introduction

Unlighthouse CI enables automated performance monitoring in continuous integration pipelines. Set performance budgets, generate reports, and catch regressions before they reach production.

Install

Unlighthouse aims to keep the installation size small, for this reason it depends natively on your locally installed chrome.

To use Unlighthouse in a CI context, you'll need to install puppeteer alongside the cli.

npm install -g @unlighthouse/cli puppeteer
# yarn global add @unlighthouse/cli puppeteer
# pnpm install -g @unlighthouse/cli puppeteer

Usage

Reporting

You may want to generate reports that can be consumed by other tools. To do you can use the reporter options:

  • jsonSimple or json - A simple JSON report which contains the URL and top level scores. This is the default.
  • jsonExpanded - A full JSON report which contains the URL, score, metric and category breakdowns.
  • csv - A simple CSV report which contains the URL and score.
  • csvExpanded - A full CSV report which contains the URL, score, metric and category breakdowns.
  • lighthouseServer - Uploads the report to your lhci server
  • false - Don't generate a report.

You can specify the reporter option with the --reporter flag or the ci.reporter config option.

# Run the CI with a CSV report
unlighthouse-ci --site <your-site> --reporter csv

# Run the CI with an expanded JSON report
unlighthouse-ci --site <your-site> --reporter jsonExpanded
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  ci: {
    reporter: 'lighthouseServer',
  },
})

Budget assertions

Unlighthouse simplifies budget assertions. You can provide a single budget number which will be used to validate all pages and on all selected categories.

# Run the CI with a budget, will fail if any pages report any category less than 50
unlighthouse-ci --site <your-site> --budget 50

Alternatively, you can provide a configuration file with a list of budgets for each category.

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  ci: {
    budget: {
      'performance': 50,
      'accessibility': 100,
      'best-practices': 90,
      'seo': 90,
    },
  },
})
# Run in the directory the unlighthouse.config.ts is in
unlighthouse-ci

Build static report

Examples

Pass the --build-static flag to the binary to generate the static files needed to host the report.

# NPM
unlighthouse-ci --site harlanzw.com --debug --build-static

This will generate files in your outputPath (.unlighthouse by default).

You can upload the directory client to a static host from there.

Configuration

Configuring the CLI can be done either through the CI arguments or through a config file.

CI Options

Options
-v, --versionDisplay version number.
--site <url>Host URL to scan.
--root <path>Define the project root. Useful for changing where the config is read from or setting up sampling.
--config-file <path>Path to config file.
--output-path <path>Path to save the contents of the client and reports to.
--budget <budget>Budget (1-100), the minimum score which can pass.
--reporter <reporter>The report to generate from results. Options: csv, csvExpanded, json, jsonExpanded, lighthouseServer or false. Default: jsonSimple.
--lhci-host <lhci-host>URL of your LHCI server.
--lhci-build-token <lhci-build-token>LHCI build token, used to add data.
--lhci-auth <lhci-auth>Basic auth for your LHCI server.
--build-staticBuild a static website for the reports which can be uploaded.
--cacheEnable the caching.
--no-cacheDisable the caching.
--desktopSimulate device as desktop.
--mobileSimulate device as mobile.
--user-agent <user-agent>Specify a top-level user agent all requests will use.
--router-prefix <path>The URL path prefix for the client and API to run from.
--throttleEnable the throttling.
--samples <samples>Specify the amount of samples to run.
--sitemaps <sitemaps>Comma separated list of sitemaps to use for scanning. Providing these will override any in robots.txt.
--urls <urls>Specify explicit relative paths to scan as a comma-separated list, disabling the link crawler.
--exclude-urls <urls>Relative paths (string or regex) to exclude as a comma-separated list.
--include-urls <urls>Relative paths (string or regex) to include as a comma-separated list.
--enable-javascriptWhen inspecting the HTML wait for the javascript to execute. Useful for SPAs.
--disable-javascriptWhen inspecting the HTML, don't wait for the javascript to execute.
--enable-i18n-pagesEnable scanning pages which use x-default.
--disable-i18n-pagesDisable scanning pages which use x-default.
--disable-robots-txtDisables the robots.txt crawling.
--disable-sitemapDisables the sitemap.xml crawling.
--disable-dynamic-samplingDisables the sampling of paths.
--extra-headers <headers>Extra headers to send with the request. Example: --extra-headers foo=bar,bar=foo
--cookies <cookies>Cookies to send with the request. Example: --cookies foo=bar;bar=foo
--auth <auth>Basic auth to send with the request. Example: --auth username:password
--default-query-params <params>Default query params to send with the request. Example: --default-query-params foo=bar,bar=foo
-d, --debugDebug. Enable debugging in the logger.
-h, --helpDisplay available CLI options

Config File

If you want to configure Unlighthouse, you can create a unlighthouse.config.ts file in your cwd.

import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'example.com',
  debug: true,
  scanner: {
    device: 'desktop',
  },
})

See the Configuration section for more details and the guides.

Github Actions & Netlify Example

This example is for Github Actions and deploys a static client build to Netlify.

name: Assertions and static report

on:
  workflow_dispatch:

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Dependencies
        run: npm install -g @unlighthouse/cli puppeteer netlify-cli

      - name: Unlighthouse assertions and client
        run: unlighthouse-ci --site <your-site> --budget 75 --build-static

      - name: Deploy
        run: netlify deploy --dir=.unlighthouse --prod --message="New Release Deploy from GitHub Actions"
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
Did this page help you?