Continuous Integration

Introduction

Using the Unlighthouse CI helps you to avoid regressions on your entire sites Google Lighthouse issues.

Features

  • Perform an assertion on a specific score budget
  • Generate a static build of the report

Install

Public Early Access 🎉

Unlighthouse is currently in public early access, made possible by my sponsors 💖. Please consider becoming a sponsor or following me @harlan_zw 🐦if you like this project.

Sponsor

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 add @unlighthouse/cli puppeteer
# yarn add @unlighthouse/cli puppeteer
# pnpm add @unlighthouse/cli puppeteer

Usage

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.

unlighthouse.config.ts
export default {
  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 (.lighthouse 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.
--config-file <path>Path to config file.
--output-path <path>Path to save the contents of the client and reports to.
--budget <number>Budget (1-100), the minimum score which can pass.
--build-staticBuild a static website for the reports which can be uploaded.
--cacheEnable the caching.
--no-cacheDisable the caching.
--throttleEnable the throttling.
--samplesSpecify the amount of samples to run.
--urlsSpecify explicit relative URLs as a comma-seperated 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.
-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.

unlighthouse.config.ts

export default {
  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.

unlighthouse.yml
name: Assertions and static report

on:
  workflow_dispatch:

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

      - name: Install Dependencies
        run: npm add @unlighthouse/cli puppeteer

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

      - name: Deploy report to Netlify
        uses: nwtgck/actions-netlify@v1.2
        with:
          publish-dir: './.lighthouse/client'
          production-branch: main
          production-deploy: true
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-message: "New Release Deploy from GitHub Actions"
          enable-pull-request-comment: false
          enable-commit-comment: true
          overwrites-pull-request-comment: true
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_DEMO_SITE_ID }}
        timeout-minutes: 1