CI

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

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

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 50unlighthouse-ci --site <your-site> --budget 50

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

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 inunlighthouse-ci

Build static report

Examples

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

# NPMunlighthouse-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.
--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.

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.

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: './.unlighthouse'
          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
Table of Contents