Node API reference

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

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.

import {generateReport} from 'lighthouse';

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

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', ...]

Plugins & Custom Audits

API Reference

`lighthouse(url, flags, config, page)`

Parameters

Return value

`startFlow(page, options)`

Parameters

Return value

`navigation(page, requestor, options)`

Parameters

Return value

`startTimespan(page, options)`

Parameters

Return value

`snapshot(page, options)`

Parameters

Return value

`generateReport(result, format)`

Parameters

Return value

`auditFlowArtifacts(flowArtifacts, config)`

Parameters

Return value

`getAuditList()`

Return value

Base classes

`Audit`

`Gatherer`

Computed artifact

`NetworkRecords`

Built-in configs

`traceCategories`

Build docs developers (and LLMs) love

Plugins & Custom Audits

API Reference

​lighthouse(url, flags, config, page)

​Parameters

​Return value

​startFlow(page, options)

​Parameters

​Return value

​navigation(page, requestor, options)

​Parameters

​Return value

​startTimespan(page, options)

​Parameters

​Return value

​snapshot(page, options)

​Parameters

​Return value

​generateReport(result, format)

​Parameters

​Return value

​auditFlowArtifacts(flowArtifacts, config)

​Parameters

​Return value

​getAuditList()

​Return value

​Base classes

​Audit

​Gatherer

​Computed artifact

​NetworkRecords

​Built-in configs

​traceCategories

Build docs developers (and LLMs) love

`lighthouse(url, flags, config, page)`

Parameters

Return value

`startFlow(page, options)`

Parameters

Return value

`navigation(page, requestor, options)`

Parameters

Return value

`startTimespan(page, options)`

Parameters

Return value

`snapshot(page, options)`

Parameters

Return value

`generateReport(result, format)`

Parameters

Return value

`auditFlowArtifacts(flowArtifacts, config)`

Parameters

Return value

`getAuditList()`

Return value

Base classes

`Audit`

`Gatherer`

Computed artifact

`NetworkRecords`

Built-in configs

`traceCategories`