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>

Using npx

npx unlighthouse --site <your-site>

Install Globally 

npm add -G @unlighthouse/cli
# yarn global add @unlighthouse/cli
# pnpm add -G @unlighthouse/cli

Once installed you'll be able to use the CLI from anywhere with unlighthouse.

unlighthouse --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 do not have a chrome installation, you can install it with the following command:

npm add -G @unlighthouse/cli puppeteer
# yarn global add @unlighthouse/cli puppeteer
# pnpm add -G @unlighthouse/cli puppeteer

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.
--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.

unlighthouse.config.ts

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