Can’t make the #ChromeDevSummit this year? Catch all the content (and more!) on the livestream, or join your peers for a CDS Extended event at a hosted location nearby. To learn more, check out the Chrome Dev Summit 2019 website.

Performance Budgets (Keep Request Counts Low And File Sizes Small)

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.

The Keep Request Counts And File Sizes Small audit.
Figure 1. The Keep Request Counts And File Sizes Small audit.

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.

A custom budget report.
Figure 2. A custom budget report.

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:

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.

More information

Sources:

Feedback

Was this page helpful?
Yes
What was the best thing about this page?
It helped me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had the information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had accurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was easy to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
No
What was the worst thing about this page?
It didn't help me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was missing information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had inaccurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was hard to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.