Continuous Integration


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


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


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.


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


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 {
  site: '',
  ci: {
    budget: {
      performance: 50,
      accessibility: 100,
      'best-practices': 90,
      seo: 90,
# Run in the directory the unlighthouse.config.ts is in

Build static report


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

unlighthouse-ci --site --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.


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

CI 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: '',
  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


    runs-on: ubuntu-latest
      - uses: actions/checkout@v2
          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
          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
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_DEMO_SITE_ID }}
        timeout-minutes: 1