How to Solve Static Resource Cache Issues with Hash-Based Filenames

Example HTML snippet showing static resources a.css and b.js.

Phase 1

In early product stage with low traffic, full page reloads are fast, so updating static files is as simple as overwriting them.

Phase 2

As traffic grows, bandwidth becomes limited, so resources are cached using Expires headers. When b.js changes, the cached version prevents the new file from being requested.

Common fix: add a version query string or timestamp, e.g. <script src="b.js?v=1.0.0"></script> or <script src="b.js?t=201512171450"></script>. Updating the version forces the browser to fetch the new file.

Phase 3

When many static files exist, updating every version string becomes cumbersome and causes all cached assets to be invalidated, leading to unnecessary network traffic.

Phase 4

In large web systems, the upgrade process may create a time gap between HTML and its dependent JS. If HTML is updated before JS, users get new HTML with old JS, and vice‑versa, causing errors.

These issues stem from the version‑string approach: it forces full cache invalidation and can produce mismatched asset versions during deployment.

Solution

The most effective method is to compute a hash (e.g., MD5) of each static file and embed the hash in the filename, such as <script src="b_832wef2x.js"></script>. When the file changes, its hash changes, producing a new filename (e.g., b_933ef2x.js), which the browser treats as a new resource while unchanged files keep their cached names.

During deployment, upload the new hashed file first, then update the HTML to reference it. Because the new filename differs from the old one, both can coexist, preventing errors during the upgrade window.