Fewer Bytes on the Wire: Brotli, Minification and a Year of Browser Cache

Brotli, computed once

Everything outside the API area is compressed - published site content and portal assets alike. The interesting part is where.

A cached page is not compressed per request. When the cache entry is written, Brotli and gzip variants are written alongside it, off-thread, at Brotli quality 11 - the slowest and smallest setting there is. Every later hit serves a file that is already compressed. The expensive setting gets paid once and reused, instead of a cheaper setting being paid on every single request.

Files below 1 KB or above 8 MB skip the variants and are handled by the compression middleware instead.

Your site's own API is deliberately left out. yoursite.com/API/orders runs #/API/orders.js, is forced to application/json, and is never cached - so compressing it would mean paying CPU on every call, and it would drop Content-Length from the API log.

Minification follows the real MIME type

Minification runs when a page is rendered, never on a cache hit, and only when caching is enabled and the response is actually going into the cache.

Which minifier runs is decided by what the content genuinely is:

A bundle that the minifier cannot parse is served in its original form and the problem is logged. Half-minified JavaScript breaks a page; the original never does.

JS and CSS bundles are written as .hash files that declare their own MIME type, and are referenced without that extension:

They are cached, pre-compressed and minified on exactly the same terms as HTML.

A year of browser cache, without stale bundles

Server-side invalidation has never been the hard part - publishing bumps the site's timestamp. The browser is the hard part: the URL has not changed, so it has no reason to fetch anything.

assetUrl() stamps your own relative asset URLs with the site's last-modified time:

External and protocol-relative URLs come back untouched - we don't know when someone else's CDN last changed.

The stamp is only half of it. The other half is the cache policy that recognises it:

A versioned URL can be frozen for a year precisely because a new publish produces a new URL. And public HTML revalidates every time, so the moment you publish, visitors pick up the new ?v= references immediately. Docly answers those revalidations with a 304 and an empty body, so they cost almost nothing.

That combination - immutable assets behind a versioned URL, always-fresh HTML pointing at them - is exactly what Lighthouse's "efficient cache policy" audit is looking for.

Templates that build faster

One more thing landed on the same theme, further down in the runtime. A method call chain used to resolve its receiver more than once, and in a chain each link multiplied the work beneath it.

The templates on one of our own sites decode HTML entities using eleven chained .split().join() pairs inside a single expression. Page generation on a cache miss went from 15-29 seconds to under 0.3.