This guide shows you how to eliminate the frustrating problem of users seeing old JavaScript after you deploy updates. The fix involves a combination of cache-busting techniques on your server and CDN configuration, plus a few browser-side tricks for testing. You’ll learn the exact steps to ensure your latest code reaches every visitor.
What You’ll Need
- Access to your web server (or hosting control panel) to edit configuration files or add headers.
- If you use a CDN (like Cloudflare, Akamai, or AWS CloudFront), access to its dashboard or API.
- Basic familiarity with your site’s HTML templates (to modify script tags).
- A text editor or IDE to modify source files.
Step-by-Step
- Add a version query string to your script tags. In your HTML, change
<script src="app.js"></script>to<script src="app.js?v=2.1"></script>. Update the version number every time you deploy. This forces browsers and CDNs to treat it as a new URL. - Use content-based hashing (fingerprinting) for production. If you use a build tool (Webpack, Vite, Parcel, etc.), enable filename hashing. For example, output files like
app-8f3k2l.js. The hash changes only when the file content changes, so you never need to manually bump a version. - Set correct cache headers on your server. For hashed assets, set
Cache-Control: public, max-age=31536000, immutable. For non-hashed assets, useCache-Control: no-cache(which means the browser must revalidate with the server before using the cached copy). - Configure your CDN to respect your origin headers. In your CDN settings, ensure that “Cache Based on Origin” or “Respect Headers” is enabled. This prevents the CDN from overriding your cache-control directives.
- Purge the CDN cache after deployment. Most CDNs offer a “Purge Cache” button or API. Purge the specific files you updated, or the entire cache if you’re unsure.
- For non-hashed files, use a service worker to force updates. If you have a PWA, update the service worker version and call
skipWaiting()to activate the new service worker immediately, then fetch fresh assets. - Test with a hard reload. On your browser, press Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) to bypass the cache and see the latest version.
Common Mistakes
- Only changing the file name without updating the HTML. If you rename a file but forget to update the script tag, the browser still requests the old name.
- Using a fixed version number that you forget to bump. If you set
?v=1and never change it, the cache never invalidates. - Setting long cache headers on non-hashed files. This causes the browser to cache the file for a year without checking for updates.
- Not purging the CDN after deployment. Even if your origin has new files, the CDN may still serve the old cached copy.
- Ignoring service worker caching. If you have a service worker, it can cache assets aggressively and prevent updates.
Tips
- Use a build tool that automatically generates content hashes. This is the most reliable method.
- Set a short cache (e.g., 5 minutes) for your HTML file so that it revalidates frequently, while keeping long cache for hashed assets.
- Use a CDN that supports “Cache Tags” or “Surrogate Keys” to purge only the files related to a specific deployment.
- For debugging, use the browser’s DevTools Network tab to see the response headers and confirm the cache status (e.g., “200 from disk cache” vs “200 from network”).
- Consider using a “stale-while-revalidate” strategy in your service worker to serve old content instantly while fetching the new one in the background.
Troubleshooting
If users still see old JavaScript after following these steps:
- Check the Network tab in DevTools. If the file is served from cache, look at the response headers. If
Cache-Controlis missing or hasmax-agetoo high, fix the server configuration. - Verify that the CDN is actually purged. Some CDNs take a few minutes to propagate the purge across all edge locations.
- If you have a service worker, go to Application > Service Workers in DevTools and click “Unregister” to test without it.
- Check if your hosting provider is adding its own cache headers that override yours. Use a tool like
curl -Ito inspect the headers from the server. - If you’re using a CMS, clear any caching plugins (like WP Super Cache or W3 Total Cache) that might be serving stale HTML.
- If the issue persists, try a different browser or incognito mode to rule out a local browser cache issue.
Frequently Asked Questions
Why does my browser still show old JavaScript even after I clear the cache?
Clearing the browser cache may not clear the CDN cache or the service worker cache. You need to purge the CDN and update the service worker as well.
What’s the difference between cache-busting with a query string and filename hashing?
A query string (?v=1) is simpler but can be ignored by some proxies. Filename hashing (app-8f3k2l.js) is more reliable because the URL is completely different.
Is it safe to set Cache-Control: immutable on my assets?
Yes, but only if the filename includes a content hash. If the filename is static, immutable will prevent the browser from ever checking for updates.
How do I purge the cache on Cloudflare?
Go to the Cloudflare dashboard, select your domain, click “Caching” > “Purge Cache”, and choose “Purge Everything” or enter specific URLs.
Can I use a service worker to update assets without changing the URL?
Yes, you can use the service worker to fetch new versions and cache them, but you still need to notify the page to reload. This is more complex and often unnecessary if you use hashed filenames.
What if my CDN doesn’t support purging?
You can bypass the CDN by adding a unique query string to the asset URL, but this defeats the purpose of caching. Alternatively, switch to a CDN that supports purging.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- How to Enable Privacy Indicators on Chromebook
- How to Calculate Taxes on Overtime Pay
- VPN Not Working on iPhone? Fixes That Actually Work
- Hide & Unhide Apps on Samsung Phones
- Fix DNS Server Unavailable Error in Windows 11
- Fix iOS 17 Keyboard Not Working Properly