deepkoluguri
/
chitfund
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
chitfund/CACHE_BUSTING_GUIDE.md

6.8 KiB
Raw Blame History

🗑️ 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)