Overview
After putting in the hard work of improving your site performance, use a performance budget to prevent your site performance from regressing over time.
The Keep Request Counts Low And File Sizes Small audit lists the total number of requests and transfer size of scripts, images, and so on. This audit is available in all Lighthouse runtime environments.
You can define a budget file to impose explicit limits on some or all of these resource types. After defining your budget file the new Over Budget column tells you whether you're exceeding any of your self-defined limits.
When you define a budget file, the Performance Budgets audit only reports on the resource types that you've specified. But you can still access the information for the rest of the types from the Keep Request Counts Low And File Sizes Small audit.
Example JSON output:
"performance-budget": {
"id": "performance-budget",
"title": "Performance budget",
"description": "Keep the quantity and size of network requests under the targets set by the provided performance budget. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/budgets).",
"score": null,
"scoreDisplayMode": "informative",
"details": {
"type": "table",
"headings": [
{
"key": "label",
"itemType": "text",
"text": "Resource Type"
},
{
"key": "requestCount",
"itemType": "numeric",
"text": "Requests"
},
{
"key": "size",
"itemType": "bytes",
"text": "Transfer Size"
},
{
"key": "countOverBudget",
"itemType": "text",
"text": ""
},
{
"key": "sizeOverBudget",
"itemType": "bytes",
"text": "Over Budget"
}
],
"items": [
{
"resourceType": "image",
"label": "Image",
"requestCount": 6,
"size": 172522
},
{
"resourceType": "script",
"label": "Script",
"requestCount": 2,
"size": 446616
},
{
"resourceType": "total",
"label": "Total",
"requestCount": 22,
"size": 755199
},
{
"resourceType": "third-party",
"label": "Third-party",
"requestCount": 13,
"size": 207011,
"countOverBudget": "3 requests"
}
]
}
},
See the following pages to learn more about performance budgets:
- Start Performance Budgeting
- Performance budgets 101
- Your first performance budget
- Incorporate performance budgets into your build process
Setup
Follow the instructions below to configure Lighthouse to report when you're over budget. As mentioned before, this is only possible when running Lighthouse from the command line. The Keep Request Counts Low And File Sizes Small audit is always available in all Lighthouse runtime environments and requires no configuration.
Define a budget file
By convention the budget file is usually called budget.json but you can call it whatever you like.
The example below sets the following budgets:
- 300 kilobytes for all scripts
- 100 kilobytes for all images
- 200 kilobytes for all third-party resources
- 1000 kilobytes total
- 10 network requests for third-party resources
- 50 network requests total
[
{
"resourceSizes": [
{
"resourceType": "script",
"budget": 300
},
{
"resourceType": "image",
"budget": 100
},
{
"resourceType": "third-party",
"budget": 200
},
{
"resourceType": "total",
"budget": 1000
}
],
"resourceCounts": [
{
"resourceType": "third-party",
"budget": 10
},
{
"resourceType": "total",
"budget": 50
}
]
}
]
When you set a resourceSizes budget, you're specifying the maximum total transfer size for all
resources in that category. For example, in the code above there's a budget of 300 kilobytes for
script resources. If main.js is 200 kilobytes and ads.js is 150 kilobytes, you've exceeded
your budget.
The table below describes each of the budget.json properties.
| Name | Type | Valid Value(s) | Description |
|---|---|---|---|
resourceSizes |
Array |
An array of objects. Each object must have a resourceType and budget property.
|
The budget value specifies the total size limit in kilobytes for the category that's specified
in resourceType.
|
resourceCounts |
Array |
An array of objects. Each object must have a resourceType and budget property.
|
The budget value specifies the total resource count limit for the category that's specified
in resourceType.
|
resourceType |
String |
total, document, script, stylesheet, image,
media, font, other, or third-party.
|
total measures all page resources. document measures HTML document requests.
other includes any resource that does not match the other categories, including XHR or Fetch requests,
and data transfers over WebSocket connections. third-party measures all resources from third-party domains.
|
budget |
Integer | Any positive integer. | Depending on context, the transfer size limit or resource count limit. |
Pass the budget file as a flag
When running Lighthouse from the command line, pass the --budget-path (or --budgetPath) flag followed
by the path to your budget file in order to calculate whenever a category is over budget.
lighthouse https://youtube.com --budget-path=budget.json
Pass the --output=json flag followed by --output-path=report.json to save your report results as JSON
in the current working directory.
lighthouse https://youtube.com --budget-path=budget.json --output=json --output-path=report.json
If you were to assign your JSON report results to a variable named report you could access your
Keep Request Counts And File Sizes Small and Performance Budgets data from
report.audits['resource-summary'] and report.audits['performance-budget'], respectively.
Recommendations
Explore the related audits and guides below to learn how to stay within your budget for each resourceType
category.
documentscriptstylesheetimagemedia
More information
Sources: