Total page weight: the 1600 KB and 5000 KB thresholds

What total page weight is

Total page weight is the sum of the documents and sub-resources one page load downloads. It matters most on a metered or slow connection, where it converts directly into waiting, and it is the number that best predicts how a page behaves on a phone in a place with poor coverage.

Images are usually the largest share and the easiest to cut, through a modern format and a size that matches the layout rather than the original upload. JavaScript is the next largest and the hardest, because cutting it means removing a dependency rather than re-encoding a file.

What squirrel checks

The rule scores each crawled page on its own weight and reports the heaviest one. A page’s weight is its HTML document, which already holds its inline CSS and JavaScript, plus the external CSS, script, image and font files it loads. The 1,600 KB and 5,000 KB thresholds describe one page load, so the score sums nothing across the site and the result does not depend on how many pages were crawled. The site figures below are information only.

A resource shared by several pages counts toward every page that loads it, and counts once within a page, by URL. The rule emits one check named total-byte-weight, scored on the heaviest page:

• Passing when every page is under 1,600 KB.
• Warning when the heaviest page is from 1,600 KB up to but not including 5,000 KB, with (heavy page) after the message.
• Failing when the heaviest page is 5,000 KB or above, with (very heavy) after the message.

The message names the heaviest page and its weight, and how many pages are over each threshold: Heaviest page: https://example.com/gallery 5510KB (2 over 1600KB, 1 over 5000KB). A page over 5,000 KB is also counted as over 1,600 KB. The threshold comparison uses the unrounded weight, while the message prints it rounded.

When the crawl produced no resource-size record and no script record at all, the rule estimates the first page instead, at 30 KB per stylesheet, 50 KB per script and 100 KB per image. An empty record still counts as present, so a crawl that collected the containers but measured nothing reports each page by its HTML only. In that case the message opens Estimated heaviest page: and the details record that it is an estimate.

The details carry the heaviest page’s URL and weight, the number of pages analyzed, the number over each threshold, and that page’s breakdown: the HTML total, inline code included, and the external CSS, JavaScript, image and font totals. A bucket with nothing in it is left out.

Site total and average page weight

Two site figures show how heavy the site is overall and how a change moves the whole site, which the heaviest page alone does not. They are information only: neither changes whether the check passes, warns or fails.

• Site total (siteTotalKb): every scored page’s HTML, plus each external resource those pages load, counted once however many pages share it.
• Average page (pageAverageKb): the mean of the per-page weights the score uses, so a shared stylesheet counts toward every page that loads it.

Both are in KB and appear in the details and at the end of the message, after any (heavy page) or (very heavy): Heaviest page: https://example.com/gallery 2010KB (1 over 1600KB, 0 over 5000KB) (heavy page). Not scored: site total 2020KB across 2 pages, shared files counted once; average page 1010KB. A resource that could not be sized adds nothing to either. When the rule falls back to the estimate, it reports neither.

Size basis

The HTML size is the response size the crawler recorded for the page: the Content-Length the server sent, which is the transfer size, or the decoded body length when it sent none. It is applied the same way on the streaming and resident engines. Error pages, pages blocked by a bot challenge and non-HTML responses are not scored. Inline <style> and <script> code is part of that size, so it is not counted a second time. A page with no recorded size is weighed by its inline CSS and JavaScript instead, measured by text length. That inline JavaScript excludes any <script> whose type mentions json or template, so JSON-LD is not counted as code. External resources use the size from a HEAD request, or the fetched body for scripts.

Limits

If a resource cannot be sized, for example a HEAD response with no Content-Length, it adds nothing to the page’s weight and the rule says so: the message gives the number of resources that could not be sized, right after the threshold counts, and the details carry unsizedResources. Treat the weight as a lower bound in that case.

Fonts are the woff, woff2, ttf, otf and eot files a page names directly: a <link rel="preload" as="font">, or a url() source in an @font-face rule inside an inline <style>. Only same-site files are sized, so a font, stylesheet or image served from another host, such as a CDN, is not counted. A font that only an external stylesheet declares is not found, because stylesheet files are not read, so a site that loads all its fonts from a .css file adds nothing for fonts. Resource checks run under a time budget, so on a very large crawl some resources may go unmeasured.

Elements inside <noscript> are skipped: a browser with scripting enabled reads <noscript> content as plain text, so nothing in it loads or renders. See content inside noscript.

How to fix it

Start with images, since they are usually most of the number:

<picture>
  <source srcset="/hero.avif" type="image/avif" />
  <source srcset="/hero.webp" type="image/webp" />
  <img src="/hero.jpg" width="1200" height="630" alt="" />
</picture>

Then serve dimensions that match the layout rather than the original file, and lazy-load everything below the fold. For JavaScript, the lever is which dependencies ship rather than how they are bundled.

The common false positive is a page that loads large files only once the visitor acts, such as a video or a gallery image, but names them in the markup. The rule counts every file the page references, whether or not it downloads on first load.

Options

Configuration example

[rules."perf/total-byte-weight"]
warn_threshold_kb = 1600
error_threshold_kb = 5000

Enable / disable

Disable this rule

[rules]
disable = ["perf/total-byte-weight"]

Disable all Performance rules

[rules]
disable = ["perf/*"]

Enable only this rule

[rules]
enable = ["perf/total-byte-weight"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• images/image-file-size: the individual images making up the largest share.
• perf/js-file-size: the individual scripts.
• perf/css-file-size: the individual stylesheets.
• perf/asset-compression: whether those bytes are at least compressed in transit.

Performance findings ship in every audit next to the SEO, security and agent experience rules. See Core Web Vitals for how an agent works through a report.

References

• Reduce network payloads using text compression, web.dev
• Largest Contentful Paint, web.dev

Check your site

Run squirrel audit https://example.com and open the Performance section of the report. The report names the heaviest page with a breakdown by resource type. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.