Awesome
Budget.json
This repo
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.
Sample budget.json file
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
}
]
}
]
The Budget Object
This section provides more information on the properties that are a part of the Budget
object.
path
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$"
resourceSizes
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
}
]
resourceCounts
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
}
]
resourceType
String
The following resource types are supposed by budget.json
:
document
font
image
media
other
script
stylesheet
third-party
total
Proposed Features
- 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).
Contributing
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.