Node API reference

Complete reference for using Lighthouse programmatically as a Node module.

The Lighthouse Node API gives you full programmatic control over audits, user flows, and report generation. Install the package first:

npm install lighthouse
# or
yarn add lighthouse

Node 22 (LTS) or later is required. Some CLI flags are not available in the Node API — pass configuration directly as the third argument instead.

---

lighthouse(url, flags, config, page)

The default export. Runs a full navigation audit against a URL and returns a RunnerResult.

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

const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const result = await lighthouse('https://example.com', {port: chrome.port, output: 'html'});

console.log('Performance score:', result.lhr.categories.performance.score * 100);
await chrome.kill();

Parameters

url · string

The URL to audit. Optional when running in auditMode.

flags · object · default: "{}"

Runtime flags that override config settings. Common flags include port, output, onlyCategories, and logLevel. See Configuration reference for the full list.

config · object

A Lighthouse config object. If omitted, the default config (lighthouse:default) is used. See Configuration reference.

page · Puppeteer.Page

An existing Puppeteer Page instance. If provided, Lighthouse uses it directly instead of connecting via the port flag.

Return value

Returns Promise<LH.RunnerResult | undefined>.

lhr · object · required

The Lighthouse Result object. See Understanding results.

report · string | string[] · required

The formatted report string (HTML, JSON, or CSV). When multiple output formats are requested this is an array.

artifacts · object · required

Raw artifacts collected during the run.

---

startFlow(page, options)

Creates a UserFlow instance to record multiple steps (navigations, timespans, snapshots) in sequence, then generate a single combined flow report.

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

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

const flow = await startFlow(page, {name: 'Checkout flow'});

await flow.navigate('https://example.com');
await flow.startTimespan({stepName: 'Add to cart'});
await page.click('#add-to-cart');
await flow.endTimespan();
await flow.snapshot({stepName: 'Cart state'});

const report = flow.generateReport();
await browser.close();

Parameters

Parameter	Type	Description
page	Puppeteer.Page	Required. A Puppeteer page instance.
options	LH.UserFlow.Options	Optional. May include name (string) for the flow report title and a base config.

Return value

Returns Promise<UserFlow>. The UserFlow instance exposes .navigate(), .startTimespan(), .endTimespan(), .snapshot(), and .generateReport().

---

navigation(page, requestor, options)

Performs a single navigation-based audit. This is the function lighthouse() calls internally.

import {navigation} from 'lighthouse';

const result = await navigation(page, 'https://example.com', {
  config: {extends: 'lighthouse:default'},
  flags: {onlyCategories: ['performance']},
});

Parameters

Parameter	Type	Description
page	Puppeteer.Page | undefined	Puppeteer page to use.
requestor	LH.NavigationRequestor | undefined	URL string or a function that triggers navigation.
options	{config?, flags?}	Optional config and flags.

Return value

Returns Promise<LH.RunnerResult | undefined>.

---

startTimespan(page, options)

Begins a timespan audit that records user interactions between startTimespan and endTimespan. Use this to measure the performance impact of a specific interaction.

import {startTimespan} from 'lighthouse';

const {endTimespan} = await startTimespan(page, {flags: {onlyCategories: ['performance']}});

await page.click('#load-more');
await page.waitForSelector('.new-items');

const result = await endTimespan();

Parameters

Parameter	Type	Description
page	Puppeteer.Page	The page to instrument.
options	{config?, flags?}	Optional config and flags.

Return value

Returns Promise<{endTimespan: () => Promise<LH.RunnerResult | undefined>}>.

---

snapshot(page, options)

Audits the current state of the page without navigating. Useful for auditing the state of a single-page application after user interaction.

import {snapshot} from 'lighthouse';

await page.goto('https://example.com/app');
await page.click('#open-modal');

const result = await snapshot(page, {flags: {onlyCategories: ['accessibility']}});

Parameters

Parameter	Type	Description
page	Puppeteer.Page	The page to snapshot.
options	{config?, flags?}	Optional config and flags.

Return value

Returns Promise<LH.RunnerResult | undefined>.

---

generateReport(result, format)

Converts a Lighthouse result or flow result object to a formatted report string.

HTML report

import {generateReport} from 'lighthouse';

const html = generateReport(runnerResult.lhr, 'html');
fs.writeFileSync('report.html', html);

import {generateReport} from 'lighthouse';

const json = generateReport(runnerResult.lhr, 'json');
const data = JSON.parse(json);

import {generateReport} from 'lighthouse';

const csv = generateReport(runnerResult.lhr, 'csv');
fs.writeFileSync('report.csv', csv);

Parameters

Parameter	Type	Default	Description
result	LH.Result | LH.FlowResult	—	The result object to format.
format	'html' | 'json' | 'csv'	'html'	Output format. 'csv' is not supported for LH.FlowResult.

Return value

Returns string.

---

auditFlowArtifacts(flowArtifacts, config)

Re-audits previously collected flow artifacts against an optional config. Useful when you want to change scoring or audits without re-running the browser.

import {auditFlowArtifacts} from 'lighthouse';

const flowResult = await auditFlowArtifacts(savedFlowArtifacts, {
  extends: 'lighthouse:default',
  settings: {onlyCategories: ['performance']},
});

Parameters

Parameter	Type	Description
flowArtifacts	LH.UserFlow.FlowArtifacts	Artifacts from a previous flow run. Includes gatherSteps and name.
config	LH.Config	Optional config to apply during the audit phase.

Return value

Returns Promise<LH.FlowResult>.

---

getAuditList()

Returns an array of all available built-in audit IDs.

import {getAuditList} from 'lighthouse';

const audits = getAuditList();
console.log(audits);
// ['is-on-https', 'redirects-http', 'service-worker', ...]

Return value

Returns string[].

---

Base classes

Audit

The base class for all Lighthouse audits. Extend this to create custom audits.

import {Audit} from 'lighthouse';

class MyAudit extends Audit {
  static get meta() {
    return {
      id: 'my-audit',
      title: 'My custom audit',
      failureTitle: 'My custom audit failed',
      description: 'Checks for a custom condition.',
      requiredArtifacts: ['URL'],
    };
  }

  static audit(artifacts) {
    const passed = artifacts.URL.finalDisplayedUrl.startsWith('https');
    return {score: passed ? 1 : 0};
  }
}

export default MyAudit;

Gatherer

The base class for all Lighthouse gatherers. Extend this to collect custom artifacts.

import {Gatherer} from 'lighthouse';

class MyGatherer extends Gatherer {
  meta = {
    supportedModes: ['navigation', 'snapshot', 'timespan'],
  };

  async getArtifact(context) {
    const value = await context.driver.executionContext.evaluate(() => {
      return document.title;
    }, {args: []});
    return value;
  }
}

export default MyGatherer;

---

Computed artifact

NetworkRecords

A computed artifact that parses devtools log entries into structured network request objects. Useful when writing custom audits that need network data.

import {NetworkRecords} from 'lighthouse';

// Inside an audit's audit() method:
const networkRecords = await NetworkRecords.request(artifacts.DevtoolsLog, context);
const slowRequests = networkRecords.filter(r => r.transferSize > 100_000);

---

Built-in configs

Export	Description
defaultConfig	The standard Lighthouse config. Equivalent to lighthouse:default.
desktopConfig	Desktop preset config. Disables mobile emulation and uses desktop throttling.

import lighthouse, {defaultConfig, desktopConfig} from 'lighthouse';

// Run with desktop config
const result = await lighthouse('https://example.com', {port: chrome.port}, desktopConfig);

---

traceCategories

An array of Chrome trace category strings that Lighthouse requires for its audits. Pass these to your own tracing setup if you collect traces externally.

import {traceCategories} from 'lighthouse';

console.log(traceCategories);
// ['toplevel', 'v8.execute', 'blink.user_timing', ...]