or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdcore-auditing.mdindex.mdreport-generation.mduser-flows.md
tile.json

tessl/npm-lighthouse

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lighthouse@12.8.x

To install, run

npx @tessl/cli install tessl/npm-lighthouse@12.8.0

index.mddocs/

Lighthouse

Lighthouse is a comprehensive web performance auditing tool that analyzes web applications and pages to collect modern performance metrics and insights on developer best practices. It provides automated auditing capabilities for web performance, accessibility, SEO, and Progressive Web App features, generating detailed reports with actionable recommendations.

Package Information

  • Package Name: lighthouse
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install lighthouse

Core Imports

ESM (recommended):

import lighthouse, { 
  startFlow, 
  navigation, 
  startTimespan, 
  snapshot, 
  generateReport,
  auditFlowArtifacts,
  getAuditList,
  traceCategories,
  Audit,
  Gatherer,
  defaultConfig,
  desktopConfig
} from 'lighthouse';

CommonJS:

const lighthouse = require('lighthouse');
const { 
  startFlow, 
  navigation, 
  startTimespan, 
  snapshot, 
  generateReport,
  auditFlowArtifacts,
  getAuditList,
  traceCategories,
  Audit,
  Gatherer,
  defaultConfig,
  desktopConfig
} = lighthouse;

Basic Usage

Single Page Audit

import lighthouse from 'lighthouse';
import * as chromeLauncher from 'chrome-launcher';

// Launch Chrome
const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});

// Run Lighthouse audit
const runnerResult = await lighthouse('https://example.com', {
  logLevel: 'info',
  output: 'html',
  port: chrome.port,
});

// Generate and save report
const reportHtml = runnerResult.report;
await chrome.kill();

User Flow Testing

import { startFlow } from 'lighthouse';
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();

// Start user flow
const flow = await startFlow(page, {name: 'My User Journey'});

// Navigate and measure
await flow.navigate('https://example.com');
await flow.startTimespan({stepName: 'Search interaction'});
await page.type('input[type="search"]', 'lighthouse');
await flow.endTimespan();

const flowResult = await flow.createFlowResult();
await browser.close();

Architecture

Lighthouse is built around several key components:

  • Core Engine: Main lighthouse function and specialized measurement modes (navigation, timespan, snapshot)
  • User Flows: Multi-step journey testing with startFlow and UserFlow class
  • Audit System: Extensible audit and gatherer framework for custom measurements
  • Report Generation: Multiple output formats (HTML, JSON, CSV) with customizable reporting
  • CLI Interface: Command-line tool with comprehensive options and configuration
  • Configuration System: Flexible config files and presets for different testing scenarios

Capabilities

Core Auditing Functions

Primary functions for running Lighthouse audits in different modes and contexts.

function lighthouse(
  url?: string,
  flags?: LH.Flags,
  config?: LH.Config,
  page?: LH.Puppeteer.Page
): Promise<LH.RunnerResult | undefined>;

function navigation(
  page?: LH.Puppeteer.Page,
  requestor?: LH.NavigationRequestor,
  options?: { config?: LH.Config; flags?: LH.Flags }
): Promise<LH.RunnerResult | undefined>;

function startTimespan(
  page: LH.Puppeteer.Page,
  options?: { config?: LH.Config; flags?: LH.Flags }
): Promise<{ endTimespan: () => Promise<LH.RunnerResult | undefined> }>;

function snapshot(
  page: LH.Puppeteer.Page,
  options?: { config?: LH.Config; flags?: LH.Flags }
): Promise<LH.RunnerResult | undefined>;

Core Auditing

User Flow Testing

Multi-step user journey testing for comprehensive web application analysis.

function startFlow(
  page: LH.Puppeteer.Page,
  options?: LH.UserFlow.Options
): Promise<UserFlow>;

class UserFlow {
  navigate(
    requestor: LH.NavigationRequestor,
    stepFlags?: LH.UserFlow.StepFlags
  ): Promise<void>;
  
  startTimespan(stepFlags?: LH.UserFlow.StepFlags): Promise<void>;
  endTimespan(): Promise<void>;
  
  snapshot(stepFlags?: LH.UserFlow.StepFlags): Promise<void>;
  createFlowResult(): Promise<LH.FlowResult>;
}

User Flow Testing

Report Generation

Generate formatted reports from Lighthouse results in multiple output formats.

function generateReport(
  result: LH.Result | LH.FlowResult,
  format?: LH.OutputMode
): string;

function auditFlowArtifacts(
  flowArtifacts: LH.UserFlow.FlowArtifacts,
  config?: LH.Config
): Promise<LH.FlowResult>;

function getAuditList(): LH.Config.AuditDefn[];

const traceCategories: string[];

Report Generation

Configuration and Extension

Configuration system and extensibility framework for custom audits and gatherers.

interface LH.Config {
  settings?: LH.Config.Settings;
  audits?: LH.Config.AuditDefn[];
  categories?: Record<string, LH.Config.Category>;
  groups?: Record<string, LH.Config.Group>;
  plugins?: string[];
}

class Audit {
  static audit(
    artifacts: LH.Artifacts,
    context: LH.Audit.Context
  ): LH.Audit.Product | Promise<LH.Audit.Product>;
}

class Gatherer {
  beforeTimespan(context: LH.Gatherer.Context): Promise<void> | void;
  afterTimespan(context: LH.Gatherer.Context): Promise<LH.Artifacts[keyof LH.Artifacts]> | LH.Artifacts[keyof LH.Artifacts];
  beforeNavigation(context: LH.Gatherer.Context): Promise<void> | void;
  afterNavigation(context: LH.Gatherer.Context): Promise<LH.Artifacts[keyof LH.Artifacts]> | LH.Artifacts[keyof LH.Artifacts];
}

Configuration and Extension

Command Line Interface

Comprehensive CLI tool for automated testing and CI/CD integration.

lighthouse <url> [options]

# Core options
--output <format>                    # Output format (json, html, csv)
--output-path <path>                # Output file path
--config-path <path>                # Custom config file
--preset <preset>                   # Quick presets (perf, desktop)

# Runtime options  
--chrome-flags <flags>              # Chrome browser flags
--port <port>                       # Chrome debugging port
--max-wait-for-load <ms>           # Navigation timeout

# Throttling options
--throttling-method <method>        # Throttling method (provided, devtools, simulate)
--throttling.rttMs <ms>            # Network RTT
--throttling.throughputKbps <kbps> # Network throughput
--throttling.cpuSlowdownMultiplier <n> # CPU throttling multiplier

# Filtering options
--only-audits <audits>             # Run specific audits only
--skip-audits <audits>             # Skip specific audits  
--only-categories <categories>      # Run specific categories only

Command Line Interface

Types

Core Result Types

interface LH.RunnerResult {
  lhr: LH.LighthouseResult;
  artifacts: LH.Artifacts;
  report: string;
}

interface LH.LighthouseResult {
  audits: Record<string, LH.AuditResult>;
  categories: Record<string, LH.Category>;
  configSettings: LH.Config.Settings;
  environment: LH.Environment;
  fetchTime: string;
  finalUrl: string;
  runWarnings: string[];
  timing: LH.Timing;
  userAgent: string;
}

interface LH.FlowResult {
  steps: LH.UserFlow.StepResult[];
  name: string;
}

Audit and Category Types

interface LH.AuditResult {
  id: string;
  title: string;
  description: string;
  score: number | null;
  scoreDisplayMode: LH.AuditResult.ScoreDisplayMode;
  displayValue?: string;
  details?: LH.AuditResult.Details;
  errorMessage?: string;
  warnings?: string[];
}

interface LH.Category {
  id: string;
  title: string;
  description?: string;
  score: number | null;
  auditRefs: LH.AuditRef[];
}

Configuration Types

interface LH.Flags {
  port?: number;
  hostname?: string;
  output?: LH.OutputMode | LH.OutputMode[];
  outputPath?: string;
  view?: boolean;
  configPath?: string;
  preset?: 'perf' | 'desktop';
  chromeFlags?: string | string[];
  maxWaitForLoad?: number;
  enableErrorReporting?: boolean;
  throttlingMethod?: 'provided' | 'devtools' | 'simulate';
  throttling?: LH.ThrottlingSettings;
  onlyAudits?: string[];
  skipAudits?: string[];
  onlyCategories?: string[];
}

interface LH.ThrottlingSettings {
  rttMs?: number;
  throughputKbps?: number;
  cpuSlowdownMultiplier?: number;
  requestLatencyMs?: number;
  downloadThroughputKbps?: number;
  uploadThroughputKbps?: number;
}