Unlighthouse

CLI

Introduction

Using the Unlighthouse CLI is the primary way to scan entire production sites.

Features

  • Accurate Performance Metrics
  • Minimal configuration

Install

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.

Sponsor

Single run

If you prefer not to add a global dependency you can run Unlighthouse once off.

Using pnpm dlx (recommended) - requires pnpm.

pnpm dlx unlighthouse --site <your-site>
# or if that doesn't work try:
# pnpm dlx unlighthouse-puppeteer --site example.com

Using npx

npx unlighthouse --site <your-site>
# or if that doesn't work try:
# npx unlighthouse-puppeteer --site example.com

With Chrome Dependency

Unlighthouse aims to keep the installation size small, for this reason it depends natively on your locally installed chrome.

If you get errors about puppeteer or chrome not being available, the easiest way to resolve it is with the unlighthouse-puppeteer binary.

unlighthouse-puppeteer --site example.com

You will need to use unlighthouse-puppeteer anywhere it says unlighthouse.

Usage

Once installed globally you'll have access to Unlighthouse through the unlighthouse binary.

Do a the default scan.

unlighthouse --site example.com --debug

Run without caching, throttle the requests and do 3 samples.

unlighthouse --site example.com --debug --no-cache --throttle --samples 3

Configuration

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

See the Configuration section for more details and the guides.

CLI 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.
--cacheEnable the caching.
--no-cacheDisable the caching.
--desktopSimulate device as desktop.
--mobileSimulate device as mobile.
--throttleEnable the throttling.
--samplesSpecify the amount of samples to run.
--urlsSpecify explicit relative URLs as a comma-seperated list.
e.g. unlighthouse --site unlighthouse.dev --urls /guide,/api,/config
--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.

unlighthouse.config.ts

export default {
  site: 'example.com',
  debug: true,
  scanner: {
    device: 'desktop'
  }
}