The Netlify Lighthouse Integration brings the popular Google Lighthouse auditing tool directly to your deploys. With the plugin installed, you get access to a full report each time you deploy your site that tells you how to improve your sites performance, accessibility, SEO, and more. You can install the plugin for your site from the Integrations Hub now with a one-click install or read more in the plugin README on how to configure it. In the latest release, we added some new features that allows you more control over what happens based on the reports. Specifying sub directories for reports, failing builds based on scores, and setting the type of experience are custom settings that give you more control. By default, the plugin requires no extra configuration. If you don’t need to configure the plugin and just want to upgrade, skip to the “Upgrade existing plugin” section.
Features in Latest Major Release 4.0
By default, the plugin will serve and audit only the build directory of the site, auditing the index.html file. With this new release, you now have more control over how directories are audited with updated configuration options. Previously, the path option would limit the audit to only the directory and/or files specified by that property and any assets outside the directory would not be reachable. With the latest change, the path option audits directories and files specified in conjunction with the build directory and all assets are reachable.
Only Serve a Sub Directory
To specify a sub directory to only audit, without reaching outside of it, there is a new serveDir option added to the netlify.toml configuration. This allows you to specify a sub directory to only be audited rather than the build directory. The path option will still allow you to run audits on specific paths, but will also run audits on the build directory.
[[plugins]]
package = "@netlify/plugin-lighthouse"
[[plugins.inputs.audits]]
path = "about/contact.html" # to audit contact.html file rather than the index.html in a sub path of the build directory
[[plugins.inputs.audits]]
path = "about" # to audit the index.html file in a sub path of the build directory
[[plugins.inputs.audits]]
serveDir = "about" # to serve only a sub directory of the build directory for an audit
# about/index.html will be audited, and files outside of this directory will not be served
Other new Features
Fail Builds When a Score isn’t Met
Wouldn’t it be nice to make sure your site always meets a certain standard? The Lighthouse plugin allows you to fail your builds if your Lighthouse scores fall below a specified score threshold in the netlify.toml configuration. Set the threshold based on performance, accessibility, best-practices, seo, or pwa.
[[plugins]]
package = "@netlify/plugin-lighthouse"
[plugins.inputs.thresholds]
performance = 0.9
accessibility = 1.0
best-practices = 0.9
seo = 0.8
pwa = 0.5
Set Locale and Language for the Report
Lighthouse results are generated in English by default, but you can return results in other languages by including the language code from any Lighthouse-supported locale in your netlify.toml file.
💡 Example to generate Lighthouse results in Spanish
[[plugins]]
package = "@netlify/plugin-lighthouse"
[plugins.inputs.settings]
locale = "es" # generates Lighthouse reports in Español
Run Lighthouse Audits for Desktop
By default, Lighthouse runs audits for the mobile device experience, but can be configured to run the desktop version. You can leave the configuration off to get the mobile-first experience or set it for desktop, there is no option for running both. You can optionally run Lighthouse audits for the desktop experience by including preset = "desktop" in your netlify.toml file:
[[plugins]]
package = "@netlify/plugin-lighthouse"
[plugins.inputs.settings]
preset = "desktop" # Optionally run Lighthouse using a desktop configuration
Then to return to running Lighthouse audits for the mobile-first experience, just remove the line preset = "desktop" and new builds will run with mobile-first experience.
Get the Latest Features
To get access to all of the new features you’ll need to have the latest version of the Lighthouse Build Plugin. Before anything else, you’ll want to make sure you have a site deploying to Netlify. You can get started for free and still see your Lighthouse reports!
Install the Lighthouse Plugin
If you don’t currently have a site with the plugin already installed, head over to the integrations page to add the plugin to your existing site.
-
Click on the Add build plugin button.
-
Search for and select the site you want to add the plugin on.
-
And that’s it, on your next deploy you can see the Lighthouse scores right in your deploy page. Also, click “View Lighthouse report” under the scores to see the full report.
Deploy Page
View Full Report
Update existing Plugin
If you are already running an older version of the plugin on your site, you’ll need to upgrade to the latest version. You can view the latest version under releases in the GitHub repository.
Update the Plugin through the Site Settings
The Lighthouse Plugin can be upgraded directly in the settings of a site it is currently installed on in the Netlify app.
-
Head to the “Site settings” and then “Plugins” for the site you are running the plugin on. You should see if a update is available directly in the UI.
-
Click “Change version” and select the release you want to update to. Then click the “Change version” button on the display to update to the version selected.
💡 If you have the Lighthouse plugin installed in your
package.jsonfile, the plugin will need to be updated manually with your package manager. You can also see in the deploy logs if you are running an outdated version.
Update the Plugin with your Package Manager
If you have the plugin installed locally in your package.json file, you can update the plugin using your package manager like the following:
# npm
npm update @netlify/plugin-lighthouse@latest
# yarn
yarn upgrade @netlify/plugin-lighthouse@latest
#pnpm
pnpm upgrade @netlify/plugin-lighthouse@latest
Feel the Power
Now the power is in your hands. Start configuring the Netlify Lighthouse plugin to what you need for your site today. Make sure those accessibility issues don’t make it into production by failing builds based on the score. Set the language you prefer to receive the reports in. Or choose to run the report based on desktop rather than a mobile-first environment. Looking for more ways to power up your builds? Check out more Build Plugins and see what’s possible or even create your own custom build plugin to fit your needs!
