Run Google Lighthouse audits on websites using headless Chrome. Get performance, accessibility, and SEO metrics.
npm install @browserless/lighthouse> @browserless/lighthouse: Browserless Lighthouse integration using puppeteer.
See the lighthouse section on our website for more information.
Using npm:
``sh`
npm install @browserless/lighthouse --save
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.
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
`js
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)
`
| 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 |
`js
// 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' })
`
Use built-in Lighthouse presets for common configurations:
`js
// 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' })
`
`js
// 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']
})
`
When using JSON output, the report includes:
`js
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
`
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 |
| Package | Purpose |
|---------|---------|
| lighthouse` | Google Lighthouse core library |
@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