🕷️ Vite PWA Cache & Dev Server Mismatch Trap

A critical cheat sheet for navigating Service Worker proxy intercepts, “Outdated Optimize Dep” 504s, and ancient UI rendering during local development.

💥 The Symptoms

🕰️ Ancient Version Rendering: The browser shows a UI/UX from hours or days ago, completely ignoring your latest code changes.
🚧 504 Outdated Optimize Dep: Vite dev server throws 504 errors on /node_modules/.vite/deps/... because the browser is requesting hashes that no longer exist.
🔁 “It works on my machine/live, but not in Playwright!” Automated agents or incognito windows fail while your main browser window magically works (or vice versa).

🕵️ The Root Cause

The culprit is usually vite-plugin-pwa or equivalent Service Workers (SW) registered on localhost or 127.0.0.1.

SW Hijacking: Once a Service Worker is registered on a domain/port, it intercepts all subsequent HTTP requests.
Aggressive Caching: It serves the index.html and assets from its CacheStorage repository.
Ghost Modules: The ancient index.html requests ancient .js module hashes (e.g., lucide-svelte.js?v=oldHash). The fresh Vite dev server rejects these with a 504, causing silent rendering failures or infinite spinners.

🛠️ The Fixes & Best Practices

1. 🧹 Nuking the Service Worker (Playwright)

When automating tests or running agents, always unregister lingering service workers before navigation if PWA caching isn’t the test target.

await page.goto("http://localhost:5174/")
await page.evaluate(async () => {
  const registrations = await navigator.serviceWorker.getRegistrations()
  for (const registration of registrations) {
    await registration.unregister()
  }
})
await page.reload({ waitUntil: "networkidle" })

2. 🚫 Disabling PWA in Dev

Ensure your vite.config.ts condition heavily disables the PWA plugin during dev mode unless specifically testing offline capabilities.

const enablePWA = process.env.VITE_DISABLE_PWA !== "1" && process.env.NODE_ENV === "production"

3. ♻️ Hard Cache Busting (Human)

If you are developing locally and see the ancient version:

Open Chrome DevTools (F12)
Go to the Application tab -> Service Workers -> click Unregister
Right-click the browser Refresh button -> Empty Cache and Hard Reload

4. 🧽 Vite Cache Purging

If Vite itself gets stuck serving corrupted dependency graphs:

sudo systemctl stop funday-frontend
rm -rf node_modules/.vite .svelte-kit
npm run prepare
sudo systemctl start funday-frontend

🧠 Core Takeaway

Never trust localhost rendering if a PWA plugin is active. The browser’s invisible Service Worker acts as a rogue proxy, serving stale code that triggers cascade failures in Vite’s ES module graph mapping. Always Clear, Unregister, and Hard-Reload.

Vite PWA Mismatch