# 🗑️ 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:

```bash
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:

```html
<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)
```bash
./deploy-frontend-only.sh
```
Now automatically includes cache-busting!

### Option 2: Clear Cache Deploy (Recommended for Major Updates)
```bash
./clear-cache-and-deploy.sh
```
More thorough - cleans everything first.

### Option 3: Force Cache Bust (Nuclear Option)
```bash
./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)
```javascript
// Press F12 to open console, then type:
window.location.reload(true)
```

### 3. Check PM2 Logs
```bash
pm2 logs luckychit-frontend --lines 20
```

### 4. Verify Build Files on Server
```bash
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
```html
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
```bash
flutter build web --build-number=$(date +%s)
```
- Adds unique number to build
- Forces Flutter to regenerate hash
- Breaks browser cache keys

### Web Renderer
```bash
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**
```bash
./force-cache-bust.sh
```

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

### Issue: PM2 serving old files

**Solution:**
```bash
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:**
```bash
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

```bash
# 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:
```bash
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)