@browserless/lighthouse: Browserless Lighthouse integration using puppeteer.

See the lighthouse section on our website for more information.

Install

Using npm:

npm install @browserless/lighthouse --save

About

This package provides Google Lighthouse integration for browserless, allowing you to run performance, accessibility, SEO, and best practices audits on any URL using your existing browserless setup.

What this package does

The @browserless/lighthouse package allows you to:

• Run Lighthouse audits with full performance, accessibility, SEO, and PWA analysis
• Generate reports in JSON, HTML, or CSV formats
• Use Lighthouse presets for desktop or mobile configurations
• Customize audits by selecting specific categories or skipping certain checks
• Integrate seamlessly with your existing browserless browser instance

Usage

const createLighthouse = require('@browserless/lighthouse')
const createBrowser = require('browserless')

// Create a browserless instance
const browser = createBrowser()

// Create the lighthouse function with teardown support
const lighthouse = createLighthouse(async teardown => {
  const browserless = await browser.createContext()
  teardown(() => browserless.destroyContext())
  return browserless
})

// Run an audit
const report = await lighthouse('https://example.com')
console.log(report.categories.performance.score)

Options

Option	Type	Default	Description
output	string	'json'	Report format: 'json', 'html', or 'csv'
timeout	number	—	Audit timeout in milliseconds
preset	string	—	Lighthouse preset: 'lr-desktop', 'lr-mobile', etc.
flags	object	—	Lighthouse flags
onlyAudits	string[]	—	Run only specific audits
skipAudits	string[]	—	Skip specific audits
onlyCategories	string[]	—	Run only specific categories

Output formats

// JSON (default) - returns the Lighthouse Result object (lhr)
const jsonReport = await lighthouse(url, { output: 'json' })
console.log(jsonReport.categories.performance) // 0.95

// HTML - returns the full HTML report as a string
const htmlReport = await lighthouse(url, { output: 'html' })
await fs.writeFile('report.html', htmlReport)

// CSV - returns CSV-formatted data
const csvReport = await lighthouse(url, { output: 'csv' })

Lighthouse presets

Use built-in Lighthouse presets for common configurations:

// Desktop configuration (higher viewport, no throttling)
const report = await lighthouse(url, { preset: 'lr-desktop' })

// Mobile configuration (smaller viewport, CPU/network throttling)
const report = await lighthouse(url, { preset: 'lr-mobile' })

Customizing audits

// Run only accessibility audits
const report = await lighthouse(url, {
  onlyAudits: ['accessibility']
})

// Run only specific categories
const report = await lighthouse(url, {
  onlyCategories: ['performance', 'accessibility']
})

// Skip specific audits
const report = await lighthouse(url, {
  skipAudits: ['uses-http2', 'bf-cache']
})

Report structure (JSON)

When using JSON output, the report includes:

const report = await lighthouse(url)

// Categories with scores (0-1)
report.categories.performance.score      // Performance score
report.categories.accessibility.score    // Accessibility score
report.categories.seo.score              // SEO score
report.categories['best-practices'].score // Best practices score
report.categories.pwa.score              // PWA score (if applicable)

// Individual audits
report.audits['first-contentful-paint'].numericValue  // FCP in ms
report.audits['largest-contentful-paint'].numericValue // LCP in ms
report.audits['cumulative-layout-shift'].numericValue  // CLS score
report.audits['total-blocking-time'].numericValue      // TBT in ms

// Configuration used
report.configSettings

How it fits in the monorepo

This is an extended functionality package for performance auditing:

Consumer	Purpose
@browserless/cli	Powers the browserless lighthouse command
User applications	Performance monitoring, CI/CD quality gates

Dependencies

Package	Purpose
lighthouse	Google Lighthouse core library

License

@browserless/lighthouse © Microlink, released under the MIT License.
Authored and maintained by Microlink with help from contributors.

The logo has been designed by xinh studio.

microlink.io · GitHub microlinkhq · X @microlinkhq