-
Notifications
You must be signed in to change notification settings - Fork 29
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat!: Run plugin on live deploy URL by default #588
Changes from 8 commits
c22cd16
9e33c9a
c5751e8
9b66701
841ce2f
7fa7d3a
8e7d31f
acd78ec
c2daeae
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -73,32 +73,25 @@ The lighthouse scores are automatically printed to the **Deploy log** in the Net | |
|
||
To customize how Lighthouse runs audits, you can make changes to the `netlify.toml` file. | ||
|
||
By default, the plugin will serve and audit the build directory of the site, inspecting the `index.html`. | ||
You can customize the behavior via the `audits` input: | ||
By default, the plugin will run after your build is deployed on the live deploy permalink, inspecting the home path `/`. | ||
You can add additional configuration and/or inspect a different path, or multiple additional paths by adding configuration in the `netlify.toml` file: | ||
|
||
```toml | ||
[[plugins]] | ||
package = "@netlify/plugin-lighthouse" | ||
|
||
# Set minimum thresholds for each report area | ||
[plugins.inputs.thresholds] | ||
performance = 0.9 | ||
|
||
# to audit a sub path of the build directory | ||
# to audit a path other than / | ||
# route1 audit will use the top level thresholds | ||
[[plugins.inputs.audits]] | ||
path = "route1" | ||
|
||
# you can specify output_path per audit, relative to the path | ||
# you can optionally specify an output_path per audit, relative to the path, where HTML report output will be saved | ||
output_path = "reports/route1.html" | ||
|
||
# to audit an HTML file other than index.html in the build directory | ||
[[plugins.inputs.audits]] | ||
path = "contact.html" | ||
|
||
# to audit an HTML file other than index.html in a sub path of the build directory | ||
[[plugins.inputs.audits]] | ||
path = "pages/contact.html" | ||
|
||
# to audit a specific absolute url | ||
[[plugins.inputs.audits]] | ||
url = "https://www.example.com" | ||
|
@@ -107,11 +100,42 @@ You can customize the behavior via the `audits` input: | |
[plugins.inputs.audits.thresholds] | ||
performance = 0.8 | ||
|
||
``` | ||
|
||
#### Fail a deploy based on score thresholds | ||
|
||
By default, the lighthouse plugin will run _after_ your deploy has been successful, auditing the live deploy content. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is it worth adding a note about the limitations, e.g. the site needs to be pre-built – no SSR etc There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Great callout! I've added a sentence that uses similar wording to what we currently have on the docs page 👍 |
||
To run the plugin _before_ the deploy is live, use the `fail_deploy_on_score_thresholds` input to instead run during the `onPostBuild` event. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Earlier on the page, under "The lighthouse scores are automatically printed to the Deploy log in the Netlify UI. For example:" the example deploy log output shows the plugin running at the ![]() Since this is no longer the default behavior, and this option isn't introduced until after the deploy log example, it could be helpful to update the deploy log example to be more representative of what folks get by default. |
||
This will statically serve your build output folder, and audit the `index.html` (or other file if specified as below). Please note that sites or site paths using SSR/ISR (server-side rendering or Incremental Static Regeneration) cannot be served and audited in this way. | ||
|
||
Using this configuration, if minimum threshold scores are supplied and not met, the deploy will fail. Set the threshold based on `performance`, `accessibility`, `best-practices`, `seo`, or `pwa`. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. earlier on the page, the code sample under "Then add the plugin to your netlify.toml configuration file:" shows thresholds being configured without ![]() Since the thresholds won't do anything without |
||
|
||
```toml | ||
[[plugins]] | ||
package = "@netlify/plugin-lighthouse" | ||
|
||
# Set the plugin to run prior to deploy, failing the build if minimum thresholds aren't set | ||
[plugins.inputs] | ||
fail_deploy_on_score_thresholds = "true" | ||
|
||
# Set minimum thresholds for each report area | ||
[plugins.inputs.thresholds] | ||
performance = 0.9 | ||
accessibility: = 0.7 | ||
|
||
# to audit an HTML file other than index.html in the build directory | ||
[[plugins.inputs.audits]] | ||
path = "contact.html" | ||
|
||
# to audit an HTML file other than index.html in a sub path of the build directory | ||
[[plugins.inputs.audits]] | ||
path = "pages/contact.html" | ||
|
||
# to serve only a sub directory of the build directory for an audit | ||
# pages/index.html will be audited, and files outside of this directory will not be served | ||
[[plugins.inputs.audits]] | ||
serveDir = "pages" | ||
|
||
``` | ||
|
||
### Run Lighthouse audits for desktop | ||
|
@@ -148,18 +172,6 @@ Updates to `netlify.toml` will take effect for new builds. | |
locale = "es" # generates Lighthouse reports in Español | ||
``` | ||
|
||
### Fail Builds Based on Score Thresholds | ||
|
||
By default, the Lighthouse plugin will report the findings in the deploy logs. To fail a build based on a specific score, specify the inputs thresholds in your `netlify.toml` file. Set the threshold based on `performance`, `accessibility`, `best-practices`, `seo`, or `pwa`. | ||
|
||
```toml | ||
[[plugins]] | ||
package = "@netlify/plugin-lighthouse" | ||
|
||
[plugins.inputs.thresholds] | ||
performance = 0.9 | ||
``` | ||
|
||
### Run Lighthouse Locally | ||
|
||
Fork and clone this repo. | ||
|
@@ -173,21 +185,13 @@ yarn local | |
|
||
## Preview Lighthouse results within the Netlify UI | ||
|
||
Netlify offers an experimental feature through Netlify Labs that allows you to view Lighthouse scores for each of your builds on your site's Deploy Details page with a much richer format. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This section was incorrectly referencing the feature being in Labs, seems it got missed in a previous cleanup. I've also added some new screenshots to bring them a bit more up to date |
||
|
||
You'll need to install the [Lighthouse build plugin](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install) on your site and then enable this experimental feature through Netlify Labs. | ||
|
||
<img width="1400" alt="Deploy view with Lighthouse visualizations" src="https://user-images.githubusercontent.com/79875905/160019039-c3e529de-f389-42bc-a3d4-458c90d59e6a.png"> | ||
|
||
If you have multiple audits (directories, paths, etc) defined in your build, we will display a roll-up of the average Lighthouse scores for all the current build's audits plus the results for each individual audit. | ||
The Netlify UI allows you to view Lighthouse scores for each of your builds on your site's Deploy Details page with a much richer format. | ||
|
||
<img width="1400" alt="Deploy details with multiple audit Lighthouse results" src="https://user-images.githubusercontent.com/79875905/160019057-d29dffab-49f3-4fbf-a1ac-1f314e0cd837.png"> | ||
You'll need to first install the [Lighthouse build plugin](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install) on your site. | ||
|
||
Some items of note: | ||
<img width="1400" alt="Deploy view with Lighthouse visualizations" src="https://github.com/netlify/netlify-plugin-lighthouse/assets/20773163/144d7bd3-5b7b-4a18-826e-c8d582f92fab"> | ||
|
||
- The [Lighthouse Build Plugin](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install) must be installed on your site(s) in order for these score visualizations to be displayed. | ||
- This Labs feature is currently only enabled at the user-level, so it will need to be enabled for each individual team member that wishes to see the Lighthouse scores displayed. | ||
If you have multiple audits (e.g. multiple paths) defined in your build, we will display a roll-up of the average Lighthouse scores for all the current build's audits plus the results for each individual audit. | ||
|
||
Learn more in our official [Labs docs](https://docs.netlify.com/netlify-labs/experimental-features/lighthouse-visualization/). | ||
<img width="1400" alt="Deploy details with multiple audit Lighthouse results" src="https://github.com/netlify/netlify-plugin-lighthouse/assets/20773163/b9887c64-db03-40c0-b7e9-5acba081f87b"> | ||
|
||
We have a lot planned for this feature and will be adding functionality regularly, but we'd also love to hear your thoughts. Please [share your feedback](https://netlify.qualtrics.com/jfe/form/SV_1NTbTSpvEi0UzWe) about this experimental feature and tell us what you think. |
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A couple of options are specific only to the
onPostBuild
behaviour (e.g. which directory to serve, file names other thanindex.html
) so have been moved to the new/separate section