Lighthouse Audits

Lighthouse is an open-source tool from Google that audits web pages for performance, accessibility, best practices, and SEO. It provides actionable scores and specific recommendations. Every developer should know how to run and interpret a Lighthouse report.

Running Lighthouse in Chrome DevTools

The fastest way to run Lighthouse is directly in Chrome:

1. Open Chrome DevTools (F12 or right-click and select "Inspect").
2. Click the Lighthouse tab.
3. Select the categories you want to audit (Performance, Accessibility, SEO, Best Practices).
4. Choose "Mobile" or "Desktop" as the device.
5. Click Analyze page load.

Chrome will reload the page in a controlled environment and generate a report. The audit takes about 15–30 seconds.

Interpreting Scores

Each category gets a score from 0 to 100:

A perfect 100 is not always realistic or necessary. Aim for 90+ on performance, but focus on the specific metrics (LCP, CLS, INP) rather than chasing the aggregate score.

Running Lighthouse from the CLI

For automation and consistency, use the Lighthouse CLI:

# Install globally
npm install -g lighthouse

# Run an audit
lighthouse https://example.com --output html --output-path ./report.html

# Run with specific categories
lighthouse https://example.com --only-categories=performance,accessibility

# Emulate a mobile device (default)
lighthouse https://example.com --preset=desktop

The CLI produces the same report as Chrome DevTools but can be scripted and integrated into build processes.

JSON Output for Automation

lighthouse https://example.com --output json --output-path ./report.json

You can parse the JSON output to extract specific metrics:

const report = JSON.parse(fs.readFileSync('./report.json', 'utf-8'));

const lcp = report.audits['largest-contentful-paint'].numericValue;
const cls = report.audits['cumulative-layout-shift'].numericValue;
const perfScore = report.categories.performance.score * 100;

console.log(`Performance: ${perfScore}`);
console.log(`LCP: ${lcp}ms`);
console.log(`CLS: ${cls}`);

Reading the Performance Report

The performance section of a Lighthouse report includes several parts.

Metrics Section

Shows the six key timing metrics with their values and whether they pass or fail:

• First Contentful Paint (FCP)
• Largest Contentful Paint (LCP)
• Total Blocking Time (TBT)
• Cumulative Layout Shift (CLS)
• Speed Index
• Time to Interactive (TTI)

Opportunities

These are suggestions that could speed up load time, with estimated savings:

• Serve images in next-gen formats: Switch from PNG/JPEG to WebP or AVIF.
• Eliminate render-blocking resources: Defer non-critical CSS and JavaScript.
• Properly size images: Resize images to match their display dimensions.
• Reduce unused JavaScript: Remove or code-split JavaScript that is not needed on initial load.

Diagnostics

Deeper technical details about the page:

• Avoid enormous network payloads
• Minimize main-thread work
• Reduce JavaScript execution time
• Serve static assets with an efficient cache policy

Lighthouse in CI

Automate Lighthouse audits in your CI pipeline using @lhci/cli:

npm install -D @lhci/cli

Create a lighthouserc.js configuration:

module.exports = {
  ci: {
    collect: {
      url: ['http://localhost:3000/', 'http://localhost:3000/about'],
      startServerCommand: 'npm run start',
      numberOfRuns: 3,
    },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['error', { minScore: 0.9 }],
        'first-contentful-paint': ['warn', { maxNumericValue: 2000 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

Add it to your CI workflow:

- name: Run Lighthouse CI
  run: |
    npm run build
    npx lhci autorun

The assert section defines thresholds. If any page scores below the minimum, the CI job fails. The numberOfRuns setting runs the audit multiple times and takes the median, reducing noise from network variability.

Key Takeaways

• Lighthouse audits performance, accessibility, best practices, and SEO in one tool.
• Use Chrome DevTools for quick checks and the CLI for scripted audits.
• Focus on the "Opportunities" section for the highest-impact improvements.
• Use Lighthouse CI to enforce performance budgets in your pipeline.
• Run multiple audits and take the median for reliable results.