Configure a CDN for New JavaScript Assets

This guide walks through configuring a Content Delivery Network (CDN) to serve newly deployed JavaScript assets without users seeing stale or broken code. You’ll learn how to bust caches, set proper headers, and verify the rollout—whether you’re using a major CDN like Cloudflare, Fastly, or AWS CloudFront, or a self-hosted edge setup.

What You’ll Need

• Access to your CDN’s control panel or API (e.g., Cloudflare dashboard, AWS Console, Fastly service config).
• Your JavaScript files are served from a known path (e.g., /static/js/ or /assets/).
• Basic familiarity with HTTP headers (Cache-Control, ETag).
• Optional: a deployment script or CI pipeline that can run a cache purge command.

Step-by-Step

1. Decide on a cache-busting strategy. The most reliable method is to include a content hash in the filename (e.g., app-8f3k2.js) so each new build has a unique URL. Alternatively, use a query string like app.js?v=20250115, but this is less reliable because some proxies ignore query strings.
2. Configure your CDN cache behavior. In your CDN settings, create a cache rule or behavior for the path that serves your JavaScript files. Set the Cache-Control header to something like public, max-age=31536000, immutable for hashed files. This tells browsers and CDNs to cache aggressively, but because the URL changes with each deploy, users always fetch the new file when the HTML references it.
3. Ensure the HTML page itself is not cached long. The HTML file that references your JS should have Cache-Control: no-cache or max-age=0 so the browser always checks for the latest version. This is critical—if the HTML is cached, it will point to old filenames.
4. Deploy your new assets. Upload the new JavaScript files to your origin server (or object storage) with the new hashed filenames. Do not overwrite old files if you want to keep rollback ability.
5. Purge the CDN cache for the HTML page (and optionally old JS files). After deploying, go to your CDN’s purge/cache-clear tool and purge the URL(s) for your HTML page(s). If you’re using hashed filenames, you don’t need to purge the JS files themselves because their URLs are new. If you used query strings, purge the JS URLs as well.
6. Verify the new assets are served. Open your site in an incognito window or use curl -I https://yoursite.com/ to check the HTML response headers. Then fetch the new JS file URL (e.g., curl -I https://yoursite.com/static/js/app-8f3k2.js) and confirm it returns 200 OK and the correct Cache-Control header.
7. Monitor for errors. Use your browser’s DevTools Network tab to ensure no 404s for old JS files. Check your CDN analytics for a spike in cache misses—that’s expected right after a deploy, but should settle quickly.

Common Mistakes

• Forgetting to update the HTML cache. If the HTML is cached for an hour, users won’t see the new JS until the cache expires, even if the JS URL is new.
• Using query strings for versioning. Some CDNs and browsers treat app.js?v=2 as the same URL and may serve stale content. Filename hashing is the industry standard.
• Setting a short cache TTL on hashed files. If you set max-age=60, you lose the performance benefit of long-term caching. Hashed files should be cached for at least a year.
• Not purging the right URLs. Purging the JS file when you changed the filename is pointless—the old URL is gone. Focus on purging the HTML.
• Deploying files but not purging at all. If you overwrite an existing file and don’t purge, the CDN keeps serving the old version until TTL expires.

Tips

• Use a build tool like Webpack, Vite, or Rollup to automatically generate hashed filenames. They output an HTML file with the correct references, so you never manually manage versions.
• Set up a purge on deploy in your CI/CD pipeline. Most CDNs have APIs—for example, Cloudflare’s purge endpoint or AWS CloudFront’s invalidation. Automate it so you never forget.
• Consider a two-tier cache: Cache the HTML for a few seconds (e.g., max-age=5) to reduce origin load, but still pick up new deploys quickly.
• Use a staging environment to test the new assets with the CDN before going live. This catches header misconfigurations early.
• Keep old files for a while (e.g., 24 hours) to allow users who loaded the old HTML to still fetch the old JS without 404s.

Troubleshooting

Users still see the old JavaScript after deploy. First, check the HTML response headers. If Cache-Control shows max-age=3600 or similar, that’s the problem—the HTML is cached. Purge the HTML URL and set no-cache on it. Also check if your browser has a local cache; a hard refresh (Ctrl+Shift+R) can rule that out.

New JS file returns 404. Verify the file exists on the origin server with the exact name. If using hashed filenames, ensure the HTML references the new hash, not an old one. Check for typos in the deployment path.

CDN serves a stale version even after purge. Some CDNs take time to propagate purges across all edge nodes. Wait a few minutes and re-check. Also confirm you purged the correct URL—including the protocol (http vs https) and any query strings.

Mixed content errors in the console. If your HTML is served over HTTPS but the JS URL is HTTP, the browser blocks it. Ensure your CDN rewrites to HTTPS or that your origin serves HTTPS.

Cache headers not showing as expected. Check if your origin server is overriding the CDN’s headers. Some frameworks set their own Cache-Control. You may need to adjust the origin or use a CDN rule to override.

Frequently Asked Questions

Q: Why use hashed filenames instead of a query string?
Hashed filenames are unique URLs, so the CDN treats them as new files and fetches them from origin. Query strings are often ignored by caches, leading to stale content.

Q: How long should I cache JavaScript files?
If the filename contains a content hash, cache for a year (max-age=31536000). If you don’t hash, use a short TTL like 1 hour to avoid stale code.

Q: Do I need to purge old JS files after a deploy?
No, if you use hashed filenames. The old files are never requested again (unless someone has a cached HTML). You can leave them or delete them after a day.

Q: What is the ‘immutable’ directive in Cache-Control?
It tells browsers and CDNs that the file will never change, so they can skip revalidation. Use it only on hashed files.

Q: My CDN has a ‘cache everything’ option—should I use it for JS?
Yes, but only if you have hashed filenames. For non-hashed files, use ‘cache but revalidate’ to avoid serving stale code.

Q: How do I test if the CDN is serving the new file?
Use curl -I to check the response headers, and look for the Last-Modified or ETag to match your new file. Or open DevTools and check the Network tab for the file’s response.

Related

• Android Location Accuracy Settings That Save Battery
• Fix Activation Error 0x8007232b on Windows 10
• Microsoft Planner Boards: Build, Organize & Move Work