Unlighthouse Documentaion

As we strive to deliver high-quality web experiences, it's essential to prioritize performance and accessibility. Unlighthouse allows us to assess these crucial aspects, identify potential issues, and optimize web applications for an enhanced user experience.

Unlighthouse is a great tool to get an overview of site performance and identify key pages that need attention.

Full documentation from unlighthouse

Documentation created by Bill in January 2024

When to use

Accessibilty scans are always helpful to run at any point during development. Speed scans should be run early and often (ideally!) but always during content production to find troubling pages as early as possible.

How to install (Mac)

Unlighthouse needs to be installed globally. You will only need to run these the first time.

Run this command to install the package to create dynamic reports in the browser.

npm install -g unlighthouse

Run this command to install the package to generate static CSV reports 

npm install -g @unlighthouse/cli

Save Scan as CSV

Start by running and saving desktop and mobile scans as your baseline reference.

Once you run your first scan, save the file to your desktop (or another folder) as the next scan you run will overwrite the current file.

The CSV file will be saved to a hidden folder named .unlighthouse in your user directory. To enable hidden files and folders on a mac, press CMD + SHIFT + PERIOD while inside your finder window.

Once your files are unhidden, navigate to the .unlighthouse folder. You should see a file named ci-result.csv.

For Mobile results (default)

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

For Desktop results 

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

Results for a site with basic auth.

unlighthouse-ci --site <your-site> --auth username:password --desktop --reporter csv

Example with basic auth

unlighthouse-ci --site https://spoonfuls.829dev.com/ --auth spoonfuls1dev:spoonfuls1dev --desktop --reporter csv

Format Results in Tech Stack

Include these CSV scans in your project's tech stack guide.

  1. In your projects tech stack, import your first mobile scan and desktop scan as their own sheets.
  2. Address any errors and make improvements
  3. Rerun the scans and import the updated mobile and desktop scan as their own sheets.

Generate Interactive Reports

Run Desktop Scan

npx unlighthouse --site <your-site> --desktop

Run Mobile Scan

npx unlighthouse --site <your-site> --mobile

Run Scan with Basic Authentication

You may need to turn off basic authentication if you run into issues with the scan only getting a few pages.

Site indexing should be turned on when running these scans during development.

npx unlighthouse --site <your-site> --auth username:password

Example 

npx unlighthouse --site https://spoonfuls.829dev.com/ --auth spoonfuls1dev:spoonfuls1dev --desktop