tessl/npm-lighthouse

Automated auditing, performance metrics, and best practices for the web.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Command Line Interface

Name: tessl/npm-lighthouse
Author: tessl

The Lighthouse CLI provides a comprehensive command-line tool for automated testing, CI/CD integration, and performance monitoring. It offers extensive configuration options and multiple output formats for different use cases.

Basic Usage

Command Structure

lighthouse <url> [options]

# Examples
lighthouse https://example.com
lighthouse https://example.com --output=json
lighthouse https://example.com --config-path=./custom-config.js

Core Options

Essential options for basic Lighthouse usage.

# Output options
--output <format>              # Output format: json, html, csv (default: html)
--output-path <path>           # Output file path (without extension)
--view                         # Open report in browser after completion
--save-assets                  # Save trace and devtools log files

# Configuration options
--config-path <path>           # Path to custom configuration file
--preset <preset>              # Quick config preset: perf, desktop, experimental
--locale <locale>              # Report locale (default: en-US)
--additional-trace-categories <cats> # Additional trace categories (comma-separated)

# Basic examples
lighthouse https://example.com --output=json --output-path=./report
lighthouse https://example.com --preset=desktop --view
lighthouse https://example.com --config-path=./config.js

Usage Examples:

# Generate HTML report (default)
lighthouse https://example.com

# Generate JSON report
lighthouse https://example.com --output=json --output-path=./results/audit

# Generate multiple formats
lighthouse https://example.com --output=html --output=json --output-path=./report

# Use desktop preset
lighthouse https://example.com --preset=desktop

# Open report automatically
lighthouse https://example.com --view

Runtime Configuration

Chrome Options

Control Chrome browser behavior and connection settings.

# Chrome connection
--chrome-flags <flags>         # Chrome command-line flags (space-separated)
--port <port>                  # Chrome debugging port (default: 0)
--hostname <hostname>          # Chrome debugging hostname (default: 127.0.0.1)
--chrome-ignore-default-flags  # Don't use default Chrome flags

# Chrome behavior  
--disable-storage-reset        # Skip clearing storage before run
--disable-full-page-screenshot # Disable full page screenshots
--enable-error-reporting       # Enable error reporting to Google

# Examples
lighthouse https://example.com --chrome-flags="--headless --no-sandbox"
lighthouse https://example.com --port=9223 --hostname=127.0.0.1
lighthouse https://example.com --disable-storage-reset

Timeout and Timing Options

Control navigation timeouts and timing behavior.

# Timeout options
--max-wait-for-load <ms>       # Max wait for page load (default: 45000)

# Examples
lighthouse https://example.com --max-wait-for-load=60000

Performance Testing Options

Throttling Configuration

Control network and CPU throttling for consistent performance testing.

# Throttling method
--throttling-method <method>   # Throttling method: provided, devtools, simulate (default: simulate)

# Network throttling
--throttling.rttMs <ms>        # Network round-trip time (default varies by method)
--throttling.throughputKbps <kbps>  # Network throughput (default varies)
--throttling.requestLatencyMs <ms>  # Request latency
--throttling.downloadThroughputKbps <kbps>  # Download throughput
--throttling.uploadThroughputKbps <kbps>    # Upload throughput

# CPU throttling
--throttling.cpuSlowdownMultiplier <n>  # CPU slowdown multiplier (default varies)

# Examples
lighthouse https://example.com --throttling-method=devtools
lighthouse https://example.com --throttling.rttMs=150 --throttling.throughputKbps=1638
lighthouse https://example.com --throttling.cpuSlowdownMultiplier=4

Throttling Presets:

# Simulate slow 4G (default)
lighthouse https://example.com --throttling-method=simulate

# Use actual network conditions
lighthouse https://example.com --throttling-method=provided

# Use Chrome DevTools throttling
lighthouse https://example.com --throttling-method=devtools

Device Emulation

Control device emulation and screen settings.

# Screen emulation  
--screenEmulation.mobile <boolean>      # Enable mobile emulation (default: true)
--screenEmulation.width <pixels>        # Screen width (default: 375)
--screenEmulation.height <pixels>       # Screen height (default: 667)
--screenEmulation.deviceScaleFactor <n> # Device scale factor (default: 2)
--screenEmulation.disabled             # Disable screen emulation entirely

# User agent
--emulatedUserAgent <string>           # Custom user agent string

# Examples  
lighthouse https://example.com --screenEmulation.mobile=false --screenEmulation.width=1920
lighthouse https://example.com --emulatedUserAgent="Custom Bot 1.0"

Audit Filtering and Selection

Category and Audit Filtering

Control which audits and categories to run.

# Category filtering
--only-categories <categories>    # Run only specified categories (comma-separated)
--skip-categories <categories>    # Skip specified categories (comma-separated)

# Audit filtering  
--only-audits <audits>           # Run only specified audits (comma-separated)
--skip-audits <audits>           # Skip specified audits (comma-separated)

# Examples
lighthouse https://example.com --only-categories=performance,accessibility
lighthouse https://example.com --skip-audits=uses-http2,render-blocking-resources
lighthouse https://example.com --only-audits=first-contentful-paint,largest-contentful-paint

Additional Options

Other useful CLI options for specialized use cases.

# Content and behavior
--form-factor <factor>         # mobile or desktop form factor
--emulatedUserAgent <ua>       # Custom user agent string  
--extra-headers <headers>      # Extra HTTP headers (JSON format)
--blocked-url-patterns <patterns> # Block URL patterns during testing
--ignore-status-code           # Ignore HTTP error status codes

# Plugin system
--plugins <plugins>            # Run specified plugins (comma-separated)

# Examples
lighthouse https://example.com --form-factor=desktop
lighthouse https://example.com --emulatedUserAgent="Custom Bot 1.0"
lighthouse https://example.com --extra-headers='{"Authorization":"Bearer token"}'
lighthouse https://example.com --blocked-url-patterns=".*\\.ads\\..*,.*analytics.*"

Available Categories:

performance - Performance metrics and opportunities
accessibility - Accessibility compliance and best practices
best-practices - General web development best practices
seo - Search Engine Optimization
pwa - Progressive Web App features

Common Audit IDs:

# Performance audits
--only-audits=first-contentful-paint,largest-contentful-paint,cumulative-layout-shift,total-blocking-time,speed-index

# Accessibility audits
--only-audits=color-contrast,image-alt,label,link-name,meta-viewport

# Best practices audits
--only-audits=uses-https,is-on-https,uses-http2,no-vulnerable-libraries

Advanced Features

Gather and Audit Modes

Separate data gathering from auditing for advanced workflows.

# Gather mode - collect artifacts only
--gather-mode                  # Only gather artifacts, don't run audits
--audit-mode                   # Only run audits on existing artifacts

# Examples
# Step 1: Gather artifacts
lighthouse https://example.com --gather-mode

# Step 2: Run audits on gathered artifacts  
lighthouse --audit-mode

Debugging and Logging

Logging Options

Control logging verbosity and debugging output.

# Logging levels
--quiet                        # Suppress most output
--verbose                      # Detailed logging output

# Debug options
--list-all-audits             # List all available audits and exit
--list-trace-categories       # List trace categories and exit
--list-locales                # List all supported locales and exit
--debug-navigation            # Pause after page load for debugging
--save-assets                 # Save trace contents and devtools logs
--additional-trace-categories <cats> # Additional trace categories to collect

# Examples
lighthouse https://example.com --verbose
lighthouse https://example.com --quiet
lighthouse --list-all-audits

Chrome Debugging

Advanced Chrome debugging and connection options.

# Chrome debugging
--chrome-ignore-default-flags  # Don't use default Chrome flags

# Manual Chrome connection
lighthouse https://example.com --port=9222  # Connect to existing Chrome instance

CI/CD Integration Patterns

Basic CI/CD Usage

# Simple performance check
lighthouse https://staging.example.com \
  --output=json \
  --output-path=./lighthouse-report \
  --chrome-flags="--headless --no-sandbox" \
  --quiet

# Check exit code for failures
echo "Exit code: $?"

Advanced CI/CD Configuration

#!/bin/bash
# ci-lighthouse.sh

URL="https://staging.example.com"
OUTPUT_DIR="./lighthouse-reports"
CONFIG_PATH="./lighthouse-ci-config.js"

# Ensure clean environment
mkdir -p "$OUTPUT_DIR"

# Run Lighthouse with CI-optimized settings
lighthouse "$URL" \
  --config-path="$CONFIG_PATH" \
  --output=json \
  --output=html \
  --output-path="$OUTPUT_DIR/report" \
  --chrome-flags="--headless --no-sandbox --disable-gpu --disable-dev-shm-usage" \
  --max-wait-for-load=60000 \
  --throttling-method=simulate \
  --log-level=error \
  --quiet

# Check if report was generated successfully
if [ $? -eq 0 ]; then
  echo "✅ Lighthouse audit completed successfully"
  echo "📊 Reports saved to $OUTPUT_DIR/"
else
  echo "❌ Lighthouse audit failed"
  exit 1
fi

Performance Threshold Checking

#!/bin/bash
# threshold-check.sh

REPORT_PATH="./lighthouse-report.json"
MIN_PERFORMANCE_SCORE=80

# Extract performance score from JSON report
PERFORMANCE_SCORE=$(cat "$REPORT_PATH" | jq -r '.categories.performance.score * 100 | floor')

echo "Performance Score: $PERFORMANCE_SCORE"

if [ "$PERFORMANCE_SCORE" -lt "$MIN_PERFORMANCE_SCORE" ]; then
  echo "❌ Performance score $PERFORMANCE_SCORE is below threshold $MIN_PERFORMANCE_SCORE"
  exit 1
else
  echo "✅ Performance score meets threshold"
fi

Batch URL Testing

#!/bin/bash
# batch-audit.sh

URLS=(
  "https://example.com"
  "https://example.com/about"
  "https://example.com/contact"
  "https://example.com/products"
)

OUTPUT_DIR="./batch-reports"
mkdir -p "$OUTPUT_DIR"

for URL in "${URLS[@]}"; do
  echo "🔍 Auditing: $URL"
  
  # Clean URL for filename
  FILENAME=$(echo "$URL" | sed 's|https://||' | sed 's|/|_|g')
  
  lighthouse "$URL" \
    --output=json \
    --output=html \
    --output-path="$OUTPUT_DIR/$FILENAME" \
    --chrome-flags="--headless --no-sandbox" \
    --preset=desktop \
    --quiet
    
  if [ $? -eq 0 ]; then
    echo "✅ Completed: $URL"
  else
    echo "❌ Failed: $URL"
  fi
done

echo "📊 Batch audit completed. Reports in $OUTPUT_DIR/"

Configuration File Examples

Basic Configuration File

// lighthouse.config.js
module.exports = {
  extends: 'lighthouse:default',
  settings: {
    onlyCategories: ['performance', 'accessibility'],
    throttling: {
      rttMs: 40,
      throughputKbps: 10240,
      cpuSlowdownMultiplier: 1,
    },
    screenEmulation: {
      mobile: false,
      width: 1920,
      height: 1080,
      deviceScaleFactor: 1,
    },
  },
};

CI-Optimized Configuration

// ci-config.js
module.exports = {
  extends: 'lighthouse:default',
  settings: {
    maxWaitForLoad: 60000,
    throttlingMethod: 'simulate',
    onlyCategories: ['performance'],
    budgets: [{
      path: '/*',
      timings: [
        {metric: 'first-contentful-paint', budget: 2000},
        {metric: 'largest-contentful-paint', budget: 4000},
      ],
      resourceSizes: [
        {resourceType: 'script', budget: 500000},
        {resourceType: 'image', budget: 1000000},
      ],
    }],
  },
};

Error Handling and Troubleshooting

Common Exit Codes

# Exit code meanings:
# 0 - Success
# 1 - General error
# 2 - Configuration error
# 3 - Runtime error
# 4 - Chrome connection error

# Check specific errors
lighthouse https://example.com || {
  case $? in
    1) echo "General Lighthouse error" ;;
    2) echo "Configuration error - check config file" ;;
    3) echo "Runtime error - check URL and Chrome" ;;
    4) echo "Chrome connection error - check Chrome setup" ;;
  esac
}

Debugging Failed Runs

# Enable verbose logging for debugging
lighthouse https://example.com \
  --verbose

# Test Chrome connection
lighthouse https://example.com \
  --port=9222 \
  --chrome-flags="--remote-debugging-port=9222" \
  --verbose