Guides

Static Reports

Last updated by
Harlan Wilton
in chore: lint markdown.

Introduction

Unlighthouse CI can generate static reports in multiple formats for automated workflows, hosting, and analysis. Unlike the interactive CLI, static reports can be deployed to any web server or integrated into CI/CD pipelines.

Static reports are perfect for stakeholder reviews, automated deployments, and long-term performance tracking.

Installation

Install the CLI globally to use unlighthouse-ci:

npm install -g @unlighthouse/cli

For complete CI features, see the CI Integration Guide.

HTML Reports

You can create static, self-hosted reports for your sites using the CI. This allows you to generate an always up-to-date version of how your site is performing overall.

You can see an example of this here: https://inspect.unlighthouse.dev/.

You can generate a report like this by providing the --build-static flag.

unlighthouse-ci --site <your-site> --build-static

This will generate files in your outputPath (.unlighthouse by default). You can upload the client directory to a static host from there.

If you want to preview the static report you can run npx sirv-cli .unlighthouse/client

Note: You will need to host your site using a web server.

CloudFlare Pages Example

You should create a CloudFlare Pages site using Direct Upload.

You will use the wrangler CLI to upload the static report.

You will need to init wrangler and configure it for your requirements.

wrangler init

You can then run the following command to generate the static report and upload it to CloudFlare Pages.

unlighthouse-ci --site www.example.com --build-static && wrangler pages publish .unlighthouse

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 add -g @unlighthouse/cli puppeteer

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

      - name: Deploy report to Netlify
        uses: nwtgck/[email protected]
        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

CSV Reports

You can generate a CSV report by providing the --reporter csv or --reporter csvExpanded flag.

unlighthouse-ci --site <your-site> --reporter csv

Note: This report format is experimental and may change in the future.

This will generate a report like the following (csvExpanded sample):

URL,Score,Performance,Accessibility,Best Practices,SEO,Largest Contentful Paint,Cumulative Layout Shift,FID,Blocking,Color Contrast,Headings,Image Alts,Link Names,Errors,Inspector Issues,Images Responsive,Image Aspect Ratio,Indexable,Tap Targets
"/",93,72,100,100,100,3211.44,0,290.36,562.29,1,1,1,1,1,1,1,1,1,1
"/blog",94,77,100,100,100,3911.7,0,205.57,260.03,1,1,1,1,1,1,1,1,1,1
"/blog/2023-april",88,51,100,100,100,4925.84,0,311.24,797.95,1,1,1,1,1,1,1,1,1,1
"/blog/2023-february",96,82,100,100,100,3207.98,0,209.96,302.01,1,1,1,1,1,1,1,1,1,1
"/blog/nuxt-3-migration-cheatsheet",85,43,97,100,100,4373.88,0,1581.52,2820.75,0,1,1,1,1,1,1,1,1,1
"/blog/vue-automatic-component-imports",93,74,97,100,100,1696.51,0,793.36,1314.27,0,1,1,1,1,1,1,1,1,1
"/blog/vue-use-head-v1",82,30,97,100,100,8053.8,0,379.59,1127.99,0,1,1,1,1,1,1,1,1,1
"/projects",92,66,100,100,100,3666.86,0,322.48,625.51,1,1,1,1,1,1,1,1,1,1
"/sponsors",92,69,100,100,100,4438.15,0,362.62,408.63,1,1,1,1,1,1,1,1,1,1
"/talks",98,90,100,100,100,864.86,0,390.93,427.94,1,1,1,1,1,1,1,1,1,1

JSON Reports

You can generate a JSON report by providing the --reporter json or --reporter jsonExpanded flag.

unlighthouse-ci --site <your-site> --reporter json

Note: This report format is experimental and may change in the future.

This will generate a report like the following (json sample):

[
  {
    "path": "/",
    "score": 0.97,
    "performance": 0.87,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog",
    "score": 0.98,
    "performance": 0.91,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/2023-february",
    "score": 0.91,
    "performance": 0.65,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/modern-package-development",
    "score": 0.9,
    "performance": 0.61,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/scale-your-vue-components",
    "score": 0.87,
    "performance": 0.51,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/vue-automatic-component-imports",
    "score": 0.88,
    "performance": 0.53,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/blog/vue-use-head-v1",
    "score": 0.97,
    "performance": 0.9,
    "accessibility": 0.97,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/projects",
    "score": 0.94,
    "performance": 0.77,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/sponsors",
    "score": 0.97,
    "performance": 0.88,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  },
  {
    "path": "/talks",
    "score": 0.94,
    "performance": 0.74,
    "accessibility": 1,
    "best-practices": 1,
    "seo": 1
  }
]

LHCI Reports

You can upload your reports to a Lighthouse CI server using the lighthouseServer reporter.

You will need to provide the --lhci-host and --lhci-build-token flags.

unlighthouse-ci --site <your-site> --reporter lighthouseServer --lhci-host <lhci host> --lhci-build-token <lhci buildToken>

This will upload your reports to the Lighthouse CI server.

Basic Auth

You can provide basic auth credentials using the --lhci-auth flag.

unlighthouse-ci --site <your-site> --reporter lighthouseServer --lhci-host <lhci host> --lhci-build-token <lhci buildToken> --lhci-auth <username>:<password>
Did this page help you?