chitfund/old_docs_backup_20251105_203126/CACHE_BUSTING_GUIDE.md

🗑️ Cache Busting Guide - Flutter Web

Problem: Changes Not Showing in Production

Flutter web apps aggressively cache files for performance. This causes issues when deploying updates.

---

🎯 Quick Fix (Do This Now!)

On Production Server:

cd /home/luckychit/apps/chitfund
./force-cache-bust.sh

This will:

• ✅ Stop and delete the PM2 process
• ✅ Remove build directory
• ✅ Build with new timestamp
• ✅ Restart with fresh cache

---

🔧 What I Fixed

1. Updated index.html

Added cache control meta tags to prevent browser caching:

<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Expires" content="0">

2. Updated Deployment Scripts

• deploy-full.sh now includes cache-busting
• deploy-frontend-only.sh now includes cache-busting
• Builds with unique timestamps: --build-number=$(date +%s)

3. Created Cache-Busting Scripts

• clear-cache-and-deploy.sh - Regular cache-clearing deployment
• force-cache-bust.sh - Nuclear option for stubborn cache

---

🚀 Deployment Methods (Choose One)

Option 1: Regular Deploy (Now with Cache-Busting)

./deploy-frontend-only.sh

Now automatically includes cache-busting!

Option 2: Clear Cache Deploy (Recommended for Major Updates)

./clear-cache-and-deploy.sh

More thorough - cleans everything first.

Option 3: Force Cache Bust (Nuclear Option)

./force-cache-bust.sh

Use when cache is really stubborn.

---

🌐 Browser-Side Cache Clearing

After deploying, users may still see old version. Tell them to:

Hard Refresh (Recommended)

Browser	Windows/Linux	Mac
Chrome	Ctrl + Shift + R	Cmd + Shift + R
Firefox	Ctrl + F5	Cmd + Shift + R
Edge	Ctrl + Shift + R	Cmd + Shift + R
Safari	-	Cmd + Option + R

Clear Browser Cache (Complete)

Chrome:

1. Settings → Privacy and security
2. Clear browsing data
3. Select "Cached images and files"
4. Time range: "All time"
5. Click "Clear data"

Firefox:

1. Settings → Privacy & Security
2. Cookies and Site Data
3. Click "Clear Data"
4. Check "Cached Web Content"
5. Click "Clear"

---

🧪 Testing After Deployment

1. Test in Incognito/Private Mode

Chrome: Ctrl + Shift + N (Windows) or Cmd + Shift + N (Mac)
Firefox: Ctrl + Shift + P (Windows) or Cmd + Shift + P (Mac)

Private mode has no cache - perfect for testing!

2. Check Build Version (Browser Console)

// Press F12 to open console, then type:
window.location.reload(true)

3. Check PM2 Logs

pm2 logs luckychit-frontend --lines 20

4. Verify Build Files on Server

cd /home/luckychit/apps/chitfund/luckychit/build/web
ls -lh
# Check modification times are recent

---

🔍 Why This Happens

Flutter Web Caching Layers:

1. Browser Cache - Browsers cache HTML, CSS, JS
2. Service Worker - Flutter uses service workers for offline support
3. CDN Cache - If using CloudFlare/CDN
4. PM2 Static Server - PM2 may serve cached files
5. Build Cache - Flutter's own build cache

---

🎓 Understanding the Fixes

Cache Control Meta Tags

Cache-Control: no-cache, no-store, must-revalidate

• no-cache: Browser must revalidate before using cached version
• no-store: Don't cache at all
• must-revalidate: Cached content must be revalidated

Build Numbers

flutter build web --build-number=$(date +%s)

• Adds unique number to build
• Forces Flutter to regenerate hash
• Breaks browser cache keys

Web Renderer

flutter build web --web-renderer html

• Uses HTML renderer (more compatible)
• Alternative: canvaskit (larger files but better performance)

---

🆘 Troubleshooting

Issue: Still seeing old version after deploy

Solution 1: Hard refresh

Ctrl + Shift + R (Windows) or Cmd + Shift + R (Mac)

Solution 2: Clear service worker Open DevTools (F12) → Application → Service Workers → Unregister

Solution 3: Force cache bust

./force-cache-bust.sh

Solution 4: Clear browser cache completely Settings → Clear browsing data → Cached images and files

Issue: PM2 serving old files

Solution:

pm2 stop luckychit-frontend
pm2 delete luckychit-frontend
pm2 serve /home/luckychit/apps/chitfund/luckychit/build/web 8080 --name luckychit-frontend --spa
pm2 save

Issue: Build cache corruption

Solution:

cd /home/luckychit/apps/chitfund/luckychit
flutter clean
rm -rf .dart_tool
rm -rf build
flutter pub get
flutter build web --release

---

📋 Deployment Checklist (Cache-Aware)

• Commit and push changes
• SSH into production server
• Run cache-busting deployment script
• Check PM2 status: pm2 status
• Test in Incognito mode first
• Do hard refresh in regular browser
• Verify login screen shows updated version
• Test on mobile device (may have aggressive caching)
• Check PM2 logs for errors

---

🎯 Best Practices

For Developers:

1. Always use deployment scripts - They now include cache-busting
2. Test in Incognito - First place to verify updates
3. Version your builds - Scripts now do this automatically
4. Monitor PM2 logs - Catch issues early

For Users:

1. Hard refresh after updates - Make it a habit
2. Clear cache monthly - Prevents accumulation
3. Use latest browser version - Better cache handling
4. Report "looks wrong" - Might be cache issue

---

🔗 Quick Commands Reference

# Regular deploy (now with cache-busting)
./deploy-frontend-only.sh

# Clear cache and deploy
./clear-cache-and-deploy.sh

# Force cache bust (nuclear)
./force-cache-bust.sh

# Check PM2
pm2 status
pm2 logs luckychit-frontend

# Manual rebuild
cd /home/luckychit/apps/chitfund/luckychit
flutter clean && flutter pub get
flutter build web --release --web-renderer html --build-number=$(date +%s)
pm2 restart luckychit-frontend

---

📱 Mobile Browser Cache

Mobile browsers cache MORE aggressively!

iOS Safari:

• Settings → Safari → Clear History and Website Data

Android Chrome:

• Menu → Settings → Privacy → Clear browsing data

Or use Private/Incognito mode for testing

---

🎉 Summary

Problem: Flutter web caches aggressively
Solution: Cache-busting meta tags + timestamped builds
Deploy: Use updated scripts (automatic cache-busting)
Test: Incognito mode + hard refresh
Emergency: ./force-cache-bust.sh

---

Your deployment scripts now handle cache-busting automatically! 🚀

For your current issue, run:

ssh luckychit@192.168.8.148
cd /home/luckychit/apps/chitfund
./force-cache-bust.sh

Then do a hard refresh in your browser: Ctrl + Shift + R (Windows) or Cmd + Shift + R (Mac)