Lighthouse v3 Migration Guide

This guide is for Lighthouse v2 users who:

• Run Lighthouse from Node or the command line.
• Rely on the JSON output of Lighthouse.

If these do not apply to you, then your workflow for running Lighthouse is mostly the same. See Announcing Lighthouse 3.0 for an overview of new features and changes.

Invocation changes

Lighthouse now computes simulated performance by default and throttling settings have been heavily changed.

CLI Flags

Node Module

In Lighthouse v3, the Node module accepts the same configuration options as the CLI. This is a breaking change in the sense that many of these options were ignored in v2, whereas now they'll actually affect how Lighthouse runs.

const fs = require('fs');
const lighthouse = require('lighthouse');
async function run() {
  // `onlyCategories` was previously only available as a config setting.
  // `output` was previously only available in CLI.
  const flags = {onlyCategories: ['performance'], output: 'html'};
  const html = (await lighthouse('https://google.com/', flags)).report;
  fs.writeFileSync('report.html', html);
}

Output changes

New, top-level format in JSON output

The JSON object that Lighthouse v3 returns now contains three top-level properties:

• lhr. The results of the audits. Short for "Lighthouse Results". This was essentially the top-level object in v2, but v3 introduces breaking changes to the shape of this object, too. See Changes to the results object.
• artifacts. The data collected from Chrome while auditing. This was previously intermingled with the properties of the LHR.
• report. The formatted report HTML/JSON/CSV as a string.

Changes to the results object

As mentioned in New, top-level format in JSON output, the results of audits are no available via the lhr property. In v2, the contents of this object were essentially the top-level JSON output. However, the shape of this object itself has changed in v3. The table below lists all the changes.

• If a row has a value in both v2 and v3 columns, it means that you should replace any reference to the v2 property in your code with the v3-equivalent.
• When a row does not have a value in the v3 column, the Notes column describes your options.
• Note that items such as ID represent placeholder text.