STATIC FILES, GZIP & STALE CACHES

two separate questions

Compression answers “how many bytes do we transfer?” Caching answers “do we transfer them again?” They solve different problems. A compressed asset can still be old, and a fresh asset can still be unnecessarily large. Start by checking the response your visitor receives, not just the file you edited.

version the asset reference

When CSS or JavaScript changes, change its URL in every HTML page that uses it. A simple version query is enough for a small hand-written archive:

<link rel="stylesheet" href="/assets/css/site.css?v=20261005explore1">
<script defer src="/assets/js/site.js?v=20261005cities2"></script>

The URL is the browser’s cache key. Changing a file while leaving the old URL and a long freshness lifetime can keep visitors on the old bytes. Keep HTML short-lived so it can discover new asset URLs. Check your reverse proxy or CDN too: some configurations ignore query strings.

regenerate the compressed sibling

Nginx with gzip_static on can serve a prebuilt .gz file beside the original. If you edit site.css but leave its sibling untouched, clients accepting gzip can receive yesterday’s CSS. Generate both from the same release, keeping file permissions readable by the web server.

gzip -n -9 -c site.css > site.css.gz
gzip -t site.css.gz
gzip -dc site.css.gz | cmp - site.css

The last command succeeds only when the decompressed sibling equals the source. -n omits filename and timestamp metadata, making output reproducible. Use this procedure in a staging copy; back up your production files before replacing them.

inspect the actual response

These commands use a reserved example domain; substitute your own public URL. First inspect headers, then request compressed bytes without automatically decoding them:

curl -I https://example.org/assets/css/site.css?v=20261005explore1
curl -sS -H "Accept-Encoding: gzip" \
  https://example.org/assets/css/site.css?v=20261005explore1 -o response.gz
gzip -t response.gz

Look for Content-Encoding: gzip, an appropriate Cache-Control, and Vary: Accept-Encoding. A missing compression header means the response may simply be plain text; do not assume every downloaded file is gzip. Also check a deep article route and a missing route: a friendly error page must still return 404.

a small release checklist

Before publishing: save a backup outside the served directory, regenerate compressed files, bump asset versions consistently, validate server configuration if it changed, and check both cached and uncached responses. Open one existing deep link as well as the homepage. Finish by verifying that backup files, configuration files and private scripts cannot be requested publicly.