Integrations
Lighthouse CI Integration
Run Lighthouse on every deploy. Catch performance regressions before they hit production.
npm install -g @unlighthouse/cli puppeteer
unlighthouse-ci --site https://staging.example.com --budget 80
If any page scores below 80, the command exits with code 1—failing your CI build.
Why Unlighthouse CI?
| Google LHCI | Unlighthouse CI | |
|---|---|---|
| Setup | Complex config, URL manifest | One command |
| Pages | Manual list | Auto-discovers entire site |
| Budgets | Per-page config | Single threshold for all pages |
| Reports | JSON/HTML | Interactive dashboard, JSON, CSV |
Basic Usage
# Scan site, fail if any page < 75
unlighthouse-ci --site example.com --budget 75
# Generate static HTML report
unlighthouse-ci --site example.com --build-static
# Both: budget check + report
unlighthouse-ci --site example.com --budget 75 --build-static
Already Using LHCI Server?
Keep your existing infrastructure—Unlighthouse uploads to LHCI servers:
unlighthouse-ci --site example.com \
--reporter lighthouseServer \
--lhci-host https://lhci.yourcompany.com \
--lhci-build-token $LHCI_TOKEN
Installation for CI
CI environments need Chrome. Install puppeteer alongside the CLI:
npm install -g @unlighthouse/cli puppeteer
Puppeteer downloads a compatible Chromium binary automatically.
Performance Budgets
Simple: One Number
# Fail if ANY category on ANY page < 75
unlighthouse-ci --site example.com --budget 75
Per-Category Budgets
More control in your config:
// unlighthouse.config.ts
export default defineUnlighthouseConfig({
site: 'https://example.com',
ci: {
budget: {
'performance': 70, // Performance can be lower
'accessibility': 95, // Accessibility must be high
'best-practices': 80,
'seo': 90,
},
},
})
Run with just:
unlighthouse-ci
Report Formats
| Format | Use Case | Flag |
|---|---|---|
json | Simple scores for CI parsing | --reporter json |
jsonExpanded | Full metrics breakdown | --reporter jsonExpanded |
csv | Spreadsheet analysis | --reporter csv |
csvExpanded | Full data in CSV | --reporter csvExpanded |
lighthouseServer | Upload to LHCI server | --reporter lighthouseServer |
# Generate CSV for stakeholders
unlighthouse-ci --site example.com --reporter csvExpanded
Static Reports
Generate a shareable HTML dashboard:
unlighthouse-ci --site example.com --build-static
Output goes to .unlighthouse/. Upload that folder to any static host.
Live examples:
Configuration
Configuring the CLI can be done either through the CI arguments or through a config file.
CI Options
| Options | |
|---|---|
-v, --version | Display 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-static | Build a static website for the reports which can be uploaded. |
--cache | Enable the caching. |
--no-cache | Disable the caching. |
--desktop | Simulate device as desktop. |
--mobile | Simulate 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. |
--throttle | Enable 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-javascript | When inspecting the HTML wait for the javascript to execute. Useful for SPAs. |
--disable-javascript | When inspecting the HTML, don't wait for the javascript to execute. |
--enable-i18n-pages | Enable scanning pages which use x-default. |
--disable-i18n-pages | Disable scanning pages which use x-default. |
--disable-robots-txt | Disables the robots.txt crawling. |
--disable-sitemap | Disables the sitemap.xml crawling. |
--disable-dynamic-sampling | Disables 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, --debug | Debug. Enable debugging in the logger. |
-h, --help | Display 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 }}
GitLab CI Example
# .gitlab-ci.yml
lighthouse-audit:
image: node:20
script:
- npm install -g @unlighthouse/cli puppeteer
- unlighthouse-ci --site $SITE_URL --budget 75
artifacts:
paths:
- .unlighthouse/
expire_in: 1 week
CircleCI Example
# .circleci/config.yml
version: 2.1
jobs:
lighthouse:
docker:
- image: cimg/node:20.0-browsers
steps:
- checkout
- run: npm install -g @unlighthouse/cli
- run: unlighthouse-ci --site $SITE_URL --budget 75 --build-static
- store_artifacts:
path: .unlighthouse
Did this page help you?