CSS file too large: the 150 KB and 500 KB thresholds

What CSS file size costs

A stylesheet in <head> normally blocks rendering. The browser will not paint until it has fetched and parsed every one whose media matches and that is not disabled, so the size of those files sits directly on first paint, on slow connections and on cheap phones most of all.

Size usually comes from three places: a framework shipped whole rather than as the parts the site uses, selectors for pages that no longer exist, and no minification. Splitting a large stylesheet by route, inlining the styles the first screen needs and loading the rest asynchronously all attack the same number.

What squirrel checks

The rule runs once per crawl over the CSS resources the crawl collected, with their sizes and the pages that referenced them. It emits one or two checks:

• css-file-size, passing with the message No CSS files detected when the crawl found none.
• css-file-size, failing with the message N CSS file(s) exceed 500.0 KB and one item per file, carrying its size, HTTP status, content type and the pages that load it.
• css-file-size-warn, warning with the message N CSS file(s) exceed 150.0 KB for files above the warning threshold but not above the error one, with the same items.
• css-file-size, passing with the message All CSS files are within size limits when nothing crossed either threshold.

Both thresholds are measured against the size the crawl recorded, which is the transferred size where the response headers gave one and the decoded body length otherwise. A file whose size could not be determined is counted in neither bucket, so a resource the crawl could not fetch is silently excluded rather than reported as oversized. The fail and warn checks can both appear on the same audit, since they cover different files.

How to fix it

Split the stylesheet so a page loads only what it needs, and load the rest without blocking:

<link rel="stylesheet" href="/critical.css" />
<link rel="stylesheet" href="/rest.css" media="print" onload="this.media='all'" />

Then remove what nothing uses. A build-time purge against the templates is more reliable than reading the file, because a class used only in a rarely rendered branch is easy to delete by hand and hard to notice missing.

The common false positive is a single stylesheet deliberately shipped for the whole site and cached across every page. It still blocks the first render, so the finding is true, but the second page view pays nothing.

Options

Configuration example

[rules."perf/css-file-size"]
warn_bytes = 153600
error_bytes = 512000

Enable / disable

Disable this rule

[rules]
disable = ["perf/css-file-size"]

Disable all Performance rules

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

Enable only this rule

[rules]
enable = ["perf/css-file-size"]

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

• perf/unminified-css: whether the file is large because it was never minified.
• perf/render-blocking: the resources holding up first paint, which these files are part of.
• perf/js-file-size: the same check on JavaScript, at 250 KB and 1 MB and a higher weight.
• perf/asset-compression: whether the file is at least served compressed.

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
• link rel=stylesheet, MDN

Check your site

Run squirrel audit https://example.com and open the Performance section of the report. Every oversized file is listed with its size and the pages that load it. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.