146 lines
3.7 KiB
Markdown
146 lines
3.7 KiB
Markdown
# PWA Installation Guide
|
|
|
|
Your Tasko app is now a Progressive Web App (PWA)! Users can install it on their phones and use it like a native app.
|
|
|
|
## What's Been Added
|
|
|
|
### 1. **manifest.json**
|
|
- App name, icons, and theme colors
|
|
- Tells the browser how to install the app
|
|
|
|
### 2. **Service Worker**
|
|
- Enables offline functionality
|
|
- Caches app resources for faster loading
|
|
|
|
### 3. **Install Prompt**
|
|
- Beautiful bottom banner prompts users to install
|
|
- Shows on mobile devices automatically
|
|
|
|
### 4. **App Icons**
|
|
- Multiple sizes for different devices (72px to 512px)
|
|
|
|
## Setting Up Icons
|
|
|
|
### Option 1: Use the Icon Generator (Easiest)
|
|
1. Open `frontend/generate-icons.html` in your browser
|
|
2. Icons will auto-generate
|
|
3. Right-click each icon and "Save image as..."
|
|
4. Save them in `frontend/public/` with exact filenames shown
|
|
|
|
### Option 2: Create Custom Icons
|
|
1. Create PNG images in these sizes:
|
|
- 72x72, 96x96, 128x128, 144x144, 152x152, 192x192, 384x384, 512x512
|
|
2. Name them as: `icon-{size}x{size}.png`
|
|
3. Place in `frontend/public/` folder
|
|
|
|
### Option 3: Use an Online Tool
|
|
- [PWA Asset Generator](https://www.pwabuilder.com/)
|
|
- [RealFaviconGenerator](https://realfavicongenerator.net/)
|
|
|
|
## Testing the PWA
|
|
|
|
### On Mobile:
|
|
1. Build and deploy your app (or use npm run dev --host)
|
|
2. Open the app in Chrome/Safari on your phone
|
|
3. You'll see the install prompt at the bottom
|
|
4. Tap "Install" to add to home screen
|
|
|
|
### On Desktop (Chrome):
|
|
1. Open DevTools (F12)
|
|
2. Go to Application > Manifest
|
|
3. Click "Add to home screen" to test
|
|
|
|
### Testing Install Prompt:
|
|
```bash
|
|
# In Chrome DevTools Console:
|
|
localStorage.removeItem('installPromptDismissed')
|
|
# Then refresh the page
|
|
```
|
|
|
|
## Features Users Get
|
|
|
|
✅ **Home Screen Icon** - App appears on phone like any other app
|
|
✅ **Splash Screen** - Beautiful loading screen with your branding
|
|
✅ **Standalone Mode** - Runs without browser UI (feels native)
|
|
✅ **Offline Support** - Works without internet (basic functionality)
|
|
✅ **Fast Loading** - Cached resources load instantly
|
|
|
|
## How It Works
|
|
|
|
### Install Flow:
|
|
1. User visits your app on mobile
|
|
2. After a few seconds, install banner appears
|
|
3. User taps "Install"
|
|
4. App is added to home screen
|
|
5. User can launch from home screen like a native app
|
|
|
|
### Browser Support:
|
|
- ✅ Chrome/Edge (Android & Desktop)
|
|
- ✅ Safari (iOS 11.3+)
|
|
- ✅ Samsung Internet
|
|
- ✅ Firefox (Android)
|
|
|
|
## Customization
|
|
|
|
### Change App Name:
|
|
Edit `manifest.json`:
|
|
```json
|
|
{
|
|
"name": "Your App Name",
|
|
"short_name": "ShortName"
|
|
}
|
|
```
|
|
|
|
### Change Colors:
|
|
Edit `manifest.json`:
|
|
```json
|
|
{
|
|
"theme_color": "#667eea",
|
|
"background_color": "#667eea"
|
|
}
|
|
```
|
|
|
|
### Update Icons:
|
|
Replace the icon files in `public/` folder
|
|
|
|
## Deployment
|
|
|
|
### For Production:
|
|
1. Build your app: `npm run build`
|
|
2. Serve with HTTPS (required for PWA)
|
|
3. Icons and manifest will be included automatically
|
|
|
|
### HTTPS Requirement:
|
|
PWAs require HTTPS (except localhost). Use:
|
|
- Vercel
|
|
- Netlify
|
|
- GitHub Pages
|
|
- Any hosting with SSL certificate
|
|
|
|
## Troubleshooting
|
|
|
|
### Install prompt not showing?
|
|
- Clear browser cache
|
|
- Remove: `localStorage.removeItem('installPromptDismissed')`
|
|
- Make sure you're on HTTPS (or localhost)
|
|
- Some browsers show it after 2-3 visits
|
|
|
|
### Icons not appearing?
|
|
- Check file names match exactly: `icon-192x192.png`
|
|
- Verify they're in `public/` folder
|
|
- Clear cache and rebuild
|
|
|
|
### Service worker not registering?
|
|
- Check browser console for errors
|
|
- Make sure `service-worker.js` is in `public/` folder
|
|
- Try hard refresh (Ctrl+Shift+R)
|
|
|
|
## Next Steps
|
|
|
|
1. Generate/add your app icons
|
|
2. Test on a real mobile device
|
|
3. Deploy to a hosting service with HTTPS
|
|
4. Share the link with users!
|
|
|
|
Users will now see an install banner and can add your app to their home screen! 🎉
|