This repository tracks the current budget.json format as well as upcoming changes and features. budget.json is the format used by Lighthouse for declaring performance budgets.
NOTE: The Lighthouse npm module is updated periodically, so it doesn't necessarily reflect very recent code changes. Features affected by this are noted in the API docs below. If you don't want to wait for the updated npm package, you can install Lighthouse directly from Github to get the most up-to-date code.
The budget.json file is an array containing one or more Budget objects.
This sample budget.json file below contains two Budget objects:
- The first budget applies to all pages except those with URL path starting with
/blog. The budget sets the following thresholds: a 300KB limit on total page resources, a 150KB limit on total JavaScript resources, and a limit of 10 third-party requests. - The second budget that applies to pages with a URL path starting with
/blog. The budget sets the following thresholds: a 200KB limit on total page resources.
[
{
"path":"/*",
"resourceSizes":[
{
"resourceType":"total",
"budget":300
},
{
"resourceType":"script",
"budget":150
},
],
"resourceCounts":[
{
"resourceType":"third-party",
"budget":10
}
]
},
{
"path":"/blog",
"resourceSizes":[
{
"resourceType":"total",
"budget":200
}
]
}
]This section provides more information on the properties that are a part of the Budget object.
Optional, String, Lighthouse 5.3 & up
The path property indciates the pages that a budget applies to. This string should follow the robots.txt format.
If path is not supplied, a budget will apply to all pages.
If a page's URL path matches the path property of more than one budget in budget.json, then the last matching budget will be applied. As a result, global budgets (e.g. "path": "/*") should be listed first in budget.json, followed by the budgets that override the global budget (e.g. "path": "/blog").
Examples
Match all URL paths.
"path": "/" (This is equivalent to writing "path": "/*")
Match all URL paths starting with /articles.
"path": "/articles"
Match URL paths within the uk/ directory and ending with shopping-cart.
"path": "/uk/*/shopping-cart$"
Optional, Array
This is an array of resourceSizeBudget objects. A resourceSizeBudget object contains two properties: resourceType and budget. resourceType is one of the resource types supported by budget.json. The budget property is defined in kilobytes and refers to the transfer size of a resource.
Example
This array contains two resource size budgets: a budget of 500KB for total resources & a budget of 300KB for script resources.
[
{
"resourceType":"total",
"budget":500
},
{
"resourceType":"script",
"budget":300
}
]Optional, Array
This is an array of resourceCountBudget objects. A resourceCountBudget object consists of two required properties: resourceType and budget. resourceType is one of the resource types supported by budget.json. budget is defined in number of requests..
Example
This array contains one resource count budget: a budget of 10 requests for third-party resources.
[
{
"resourceType":"third-party",
"budget":10
}
]
String
The following resource types are supposed by budget.json:
documentfontimagemediaotherscriptstylesheetthird-partytotal
- Support setting budgets for specific files.
- Support whitelisting of first-party domains.
- Support timing-based budgets.
- Support setting budgets for the change in resource size(s).
If you have feedback or ideas on the budget.json format, please file an issue in this repo to get involved.
If you are interested in contributing to the Lighthouse budget.json implementation, please refer to the Lighthouse repo.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent