305 lines
6.8 KiB
Markdown
305 lines
6.8 KiB
Markdown
# 🗑️ 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)
|
|
|