0
# Lighthouse
1

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

4
## Package Information
5

6
- **Package Name**: lighthouse
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install lighthouse`
10

11
## Core Imports
12

13
ESM (recommended):
14

15
```javascript
16
import lighthouse, { 
17
  startFlow, 
18
  navigation, 
19
  startTimespan, 
20
  snapshot, 
21
  generateReport,
22
  auditFlowArtifacts,
23
  getAuditList,
24
  traceCategories,
25
  Audit,
26
  Gatherer,
27
  defaultConfig,
28
  desktopConfig
29
} from 'lighthouse';
30
```
31

32
CommonJS:
33

34
```javascript
35
const lighthouse = require('lighthouse');
36
const { 
37
  startFlow, 
38
  navigation, 
39
  startTimespan, 
40
  snapshot, 
41
  generateReport,
42
  auditFlowArtifacts,
43
  getAuditList,
44
  traceCategories,
45
  Audit,
46
  Gatherer,
47
  defaultConfig,
48
  desktopConfig
49
} = lighthouse;
50
```
51

52
## Basic Usage
53

54
### Single Page Audit
55

56
```javascript
57
import lighthouse from 'lighthouse';
58
import * as chromeLauncher from 'chrome-launcher';
59

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

63
// Run Lighthouse audit
64
const runnerResult = await lighthouse('https://example.com', {
65
  logLevel: 'info',
66
  output: 'html',
67
  port: chrome.port,
68
});
69

70
// Generate and save report
71
const reportHtml = runnerResult.report;
72
await chrome.kill();
73
```
74

75
### User Flow Testing
76

77
```javascript
78
import { startFlow } from 'lighthouse';
79
import puppeteer from 'puppeteer';
80

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

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

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

93
const flowResult = await flow.createFlowResult();
94
await browser.close();
95
```
96

97
## Architecture
98

99
Lighthouse is built around several key components:
100

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

108
## Capabilities
109

110
### Core Auditing Functions
111

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

114
```javascript { .api }
115
function lighthouse(
116
  url?: string,
117
  flags?: LH.Flags,
118
  config?: LH.Config,
119
  page?: LH.Puppeteer.Page
120
): Promise<LH.RunnerResult | undefined>;
121

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

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

133
function snapshot(
134
  page: LH.Puppeteer.Page,
135
  options?: { config?: LH.Config; flags?: LH.Flags }
136
): Promise<LH.RunnerResult | undefined>;
137
```
138

139
[Core Auditing](./core-auditing.md)
140

141
### User Flow Testing
142

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

145
```javascript { .api }
146
function startFlow(
147
  page: LH.Puppeteer.Page,
148
  options?: LH.UserFlow.Options
149
): Promise<UserFlow>;
150

151
class UserFlow {
152
  navigate(
153
    requestor: LH.NavigationRequestor,
154
    stepFlags?: LH.UserFlow.StepFlags
155
  ): Promise<void>;
156
  
157
  startTimespan(stepFlags?: LH.UserFlow.StepFlags): Promise<void>;
158
  endTimespan(): Promise<void>;
159
  
160
  snapshot(stepFlags?: LH.UserFlow.StepFlags): Promise<void>;
161
  createFlowResult(): Promise<LH.FlowResult>;
162
}
163
```
164

165
[User Flow Testing](./user-flows.md)
166

167
### Report Generation
168

169
Generate formatted reports from Lighthouse results in multiple output formats.
170

171
```javascript { .api }
172
function generateReport(
173
  result: LH.Result | LH.FlowResult,
174
  format?: LH.OutputMode
175
): string;
176

177
function auditFlowArtifacts(
178
  flowArtifacts: LH.UserFlow.FlowArtifacts,
179
  config?: LH.Config
180
): Promise<LH.FlowResult>;
181

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

184
const traceCategories: string[];
185
```
186

187
[Report Generation](./report-generation.md)
188

189
### Configuration and Extension
190

191
Configuration system and extensibility framework for custom audits and gatherers.
192

193
```javascript { .api }
194
interface LH.Config {
195
  settings?: LH.Config.Settings;
196
  audits?: LH.Config.AuditDefn[];
197
  categories?: Record<string, LH.Config.Category>;
198
  groups?: Record<string, LH.Config.Group>;
199
  plugins?: string[];
200
}
201

202
class Audit {
203
  static audit(
204
    artifacts: LH.Artifacts,
205
    context: LH.Audit.Context
206
  ): LH.Audit.Product | Promise<LH.Audit.Product>;
207
}
208

209
class Gatherer {
210
  beforeTimespan(context: LH.Gatherer.Context): Promise<void> | void;
211
  afterTimespan(context: LH.Gatherer.Context): Promise<LH.Artifacts[keyof LH.Artifacts]> | LH.Artifacts[keyof LH.Artifacts];
212
  beforeNavigation(context: LH.Gatherer.Context): Promise<void> | void;
213
  afterNavigation(context: LH.Gatherer.Context): Promise<LH.Artifacts[keyof LH.Artifacts]> | LH.Artifacts[keyof LH.Artifacts];
214
}
215
```
216

217
[Configuration and Extension](./configuration.md)
218

219
### Command Line Interface
220

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

223
```bash { .api }
224
lighthouse <url> [options]
225

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

232
# Runtime options  
233
--chrome-flags <flags>              # Chrome browser flags
234
--port <port>                       # Chrome debugging port
235
--max-wait-for-load <ms>           # Navigation timeout
236

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

243
# Filtering options
244
--only-audits <audits>             # Run specific audits only
245
--skip-audits <audits>             # Skip specific audits  
246
--only-categories <categories>      # Run specific categories only
247
```
248

249
[Command Line Interface](./cli.md)
250

251
## Types
252

253
### Core Result Types
254

255
```javascript { .api }
256
interface LH.RunnerResult {
257
  lhr: LH.LighthouseResult;
258
  artifacts: LH.Artifacts;
259
  report: string;
260
}
261

262
interface LH.LighthouseResult {
263
  audits: Record<string, LH.AuditResult>;
264
  categories: Record<string, LH.Category>;
265
  configSettings: LH.Config.Settings;
266
  environment: LH.Environment;
267
  fetchTime: string;
268
  finalUrl: string;
269
  runWarnings: string[];
270
  timing: LH.Timing;
271
  userAgent: string;
272
}
273

274
interface LH.FlowResult {
275
  steps: LH.UserFlow.StepResult[];
276
  name: string;
277
}
278
```
279

280
### Audit and Category Types
281

282
```javascript { .api }
283
interface LH.AuditResult {
284
  id: string;
285
  title: string;
286
  description: string;
287
  score: number | null;
288
  scoreDisplayMode: LH.AuditResult.ScoreDisplayMode;
289
  displayValue?: string;
290
  details?: LH.AuditResult.Details;
291
  errorMessage?: string;
292
  warnings?: string[];
293
}
294

295
interface LH.Category {
296
  id: string;
297
  title: string;
298
  description?: string;
299
  score: number | null;
300
  auditRefs: LH.AuditRef[];
301
}
302
```
303

304
### Configuration Types
305

306
```javascript { .api }
307
interface LH.Flags {
308
  port?: number;
309
  hostname?: string;
310
  output?: LH.OutputMode | LH.OutputMode[];
311
  outputPath?: string;
312
  view?: boolean;
313
  configPath?: string;
314
  preset?: 'perf' | 'desktop';
315
  chromeFlags?: string | string[];
316
  maxWaitForLoad?: number;
317
  enableErrorReporting?: boolean;
318
  throttlingMethod?: 'provided' | 'devtools' | 'simulate';
319
  throttling?: LH.ThrottlingSettings;
320
  onlyAudits?: string[];
321
  skipAudits?: string[];
322
  onlyCategories?: string[];
323
}
324

325
interface LH.ThrottlingSettings {
326
  rttMs?: number;
327
  throughputKbps?: number;
328
  cpuSlowdownMultiplier?: number;
329
  requestLatencyMs?: number;
330
  downloadThroughputKbps?: number;
331
  uploadThroughputKbps?: number;
332
}
333
```