Weak Caching (site-wide)

Flags sites where most pages lack caching freshness, validators, or compression.

Rule ID	perf/bad-caching
Category	Performance
Scope	Site-wide
Severity	warning
Weight	5/10

What it checks

Where perf/cache-headers and perf/compression report per page, this rule looks at the whole site and flags systemic weakness: caching mistakes that cost you on every repeat visit and behind every CDN. Across all crawled HTML responses it measures the fraction of pages that:

• declare a caching freshness lifetime (Cache-Control: max-age/s-maxage or Expires, and not no-store),
• expose a validator (ETag or Last-Modified) for cheap revalidation, and
• serve compressible bodies with gzip/Brotli/zstd compression.

Each dimension reports pass/warn/fail with the ratio and example pages.

Solution

Set Cache-Control with an appropriate max-age on every response (short for HTML, long + immutable for hashed static assets), expose an ETag or Last-Modified for cheap revalidation, and enable gzip/Brotli for text responses. Consistent caching across the whole site cuts repeat-visit load times and origin/CDN cost.

Options

This rule supports the following configuration options:

Option	Type	Default	Description
min_freshness_ratio	number	0.6	Minimum fraction of pages that should declare a freshness lifetime
min_validator_ratio	number	0.6	Minimum fraction of pages that should expose a validator (ETag or Last-Modified)
min_compression_ratio	number	0.8	Minimum fraction of compressible responses that should be gzip/Brotli compressed

Configuration Example

[rules."perf/bad-caching"]
min_freshness_ratio = 0.6
min_validator_ratio = 0.6
min_compression_ratio = 0.8

Enable / Disable

Disable this rule

[rules]
disable = ["perf/bad-caching"]

Disable all Performance rules

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

Enable only this rule

[rules]
enable = ["perf/bad-caching"]
disable = ["*"]