Node.js quickstart

Use Lighthouse programmatically as a Node module in your scripts and tooling.

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

   npm install --save-dev lighthouse chrome-launcher
   

   yarn add --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:

   Property	Type	Description
   .report	string	The report as an HTML, JSON, or CSV string, depending on the output option
   .lhr	object	The 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.