Skip to main content
The Lighthouse Node module gives you full programmatic control over audits. Use it to integrate Lighthouse into build scripts, test suites, or custom reporting pipelines.
Chrome must be installed on the machine running Lighthouse. The chrome-launcher package handles launching and connecting to it automatically.
1

Install dependencies

Install lighthouse and chrome-launcher as dev dependencies.
npm install --save-dev lighthouse chrome-launcher
2

Write your first script

The following example launches a headless Chrome instance, runs a Lighthouse audit, saves an HTML report, and prints the performance score.
audit.js
import fs from 'fs';
import lighthouse from 'lighthouse';
import * as chromeLauncher from 'chrome-launcher';

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

// `.report` is the HTML report as a string
const reportHtml = runnerResult.report;
fs.writeFileSync('lhreport.html', reportHtml);

// `.lhr` is the Lighthouse Result as a JS object
console.log('Report is done for', runnerResult.lhr.finalDisplayedUrl);
console.log('Performance score was', runnerResult.lhr.categories.performance.score * 100);

chrome.kill();
Run it with:
node audit.js
3

Access the report and result object

The lighthouse() function returns a RunnerResult with two key properties:
PropertyTypeDescription
.reportstringThe report as an HTML, JSON, or CSV string, depending on the output option
.lhrobjectThe full Lighthouse Result (LHR) object with all audit data, scores, and metrics
Access category scores and individual audit results directly from .lhr:
const lhr = runnerResult.lhr;

// Category scores (0–1, multiply by 100 for display)
console.log('Performance:', lhr.categories.performance.score * 100);
console.log('Accessibility:', lhr.categories.accessibility.score * 100);
console.log('SEO:', lhr.categories.seo.score * 100);
console.log('Best Practices:', lhr.categories['best-practices'].score * 100);

// Individual audit result
const fcp = lhr.audits['first-contentful-paint'];
console.log('FCP:', fcp.displayValue);
4

Run performance-only audits

Pass onlyCategories in the options object to limit which audit categories run. This reduces run time significantly when you only need specific data.
const flags = {onlyCategories: ['performance']};
const runnerResult = await lighthouse('https://example.com', flags);
You can also pass multiple categories:
const flags = {onlyCategories: ['performance', 'accessibility']};
const runnerResult = await lighthouse('https://example.com', flags);

​
Configuration

Pass a config object as the third argument to lighthouse() to customize audits beyond what flags allow: 
const config = {
  extends: 'lighthouse:default',
  settings: {
    onlyAudits: [
      'speed-index',
      'interactive',
    ],
  },
};

const runnerResult = await lighthouse('https://example.com', {}, config);
Extend lighthouse:default to build on the standard configuration, or omit it to start from scratch. See Configuration overview for all available options, and Node API reference for the full API surface.

Build docs developers (and LLMs) love

Get started for freeTalk to us