Clean Deploy Only - Caching, CDNs, and Clearing Chaos

So you pushed your code. You ran npm run build like a proud dev.
You deployed it.
Then you opened the site and…

❌ The styles didn’t change.
❌ Your image is still broken.
❌ That console log from 3 commits ago is still there.

Welcome to the realm of caching and CDN chaos, where your fresh deploys are haunted by ghosts of builds past.

Let’s unpack why this happens — and how to never let it happen again.

---

🧊 What’s Caching, Really?

Browsers cache static assets (HTML, JS, CSS, images) so your site loads faster.
CDNs do the same — they serve cached files from nearby servers.

That’s great… until it isn’t.

Because once those files are cached, the browser/CDN won't fetch your new ones unless:

• You tell it to

• You change the filename

• You do the digital equivalent of smacking it with a broom

---

💀 Real Symptoms of Bad Caching

• New code doesn’t show up

• Styles appear broken or outdated

• JS errors appear from old code

• Random users report “I still see the old site”

Even if your deploy is 100% perfect — they’re seeing a version from two deploys ago.

---

What’s Really Going On?

1. Static File Caching

Your CSS/JS files are cached aggressively by browsers/CDNs.

If the file name doesn't change, the browser assumes it's the same file.

2. Service Workers (PWA)

If you’re using a PWA, service workers cache entire pages.
One wrong update and your app becomes a time capsule.

3. HTML vs Asset Caching

You update index.html, but your old JS and CSS are still referenced because the file names didn’t change.

---

🧼 The Fix: Make Your Deploys Actually Clean

✅ 1. Use Hashed File Names

Build tools like Vite, Webpack, and Next.js can output files like:

main.abc123.js
styles.df456.css

This means every build gets new file names. Browsers see:

“Ah, this is new — better re-fetch it.”

Vite does this by default in vite build. Webpack needs:

output: {
  filename: '[name].[contenthash].js'
}

---

✅ 2. Set Cache-Control Headers

You want:

• HTML: no-cache, must-revalidate → always check for a new version

• JS/CSS (with hashed names): cache for a year → they’ll never change anyway

If you’re using Netlify, Vercel, or Firebase, you can configure this via headers.

---

✅ 3. Bust the Cache (Forcefully)

Old school but works:

• Append query strings to assets (e.g., style.css?v=123)

• Invalidate CDN cache (most platforms support this)

Note: Query strings don’t always bust cache on all CDNs — prefer hashed filenames if possible.

---

✅ 4. Manage Service Workers Like a Grown-Up

If you’re building a PWA and using a service worker:

• Always version your cache

• Use self.skipWaiting() and clients.claim() properly

• Prompt users to reload when a new version is available

Tools like Workbox can help automate this.

---

✅ 5. Clear the CDN Cache After Deploy

Platforms like Cloudflare, Netlify, Vercel, and AWS have:

“Purge cache” or “Invalidate build cache” buttons

Use them — especially after breaking changes.

---

Common Mistakes

---

🔍 Tools You Should Use

• source-map-explorer – Inspect your build

• vite.config.js → Check build options

• DevTools → Disable cache (for dev), check "Network → size/from cache"

---

Final Thoughts

Deploying is easy.
Deploying clean — that's a skill.

So next time your site acts haunted:

• Check your cache headers

• Hash those filenames

• Invalidate what needs to be invalidated

• And show your CDN who’s boss.

Because nothing ruins a Friday like deploying… and then realizing no one got the update

---

📚 This was part of It Worked in Dev — the blog about post-deploy pain, and how to fix it like a professional with a sense of humor.

Follow for more:

• Production traps

• Dev horror stories

• And actually useful fixes

Now go clean your deploy, champ 🚀