|
209
|
1 # PWA Setup Guide
|
|
|
2
|
|
|
3 Your site is now configured as a Progressive Web App! 🎉
|
|
|
4
|
|
|
5 ## What's Been Added
|
|
|
6
|
|
|
7 1. **manifest.json** - App configuration
|
|
|
8 2. **sw.js** - Service worker for caching and offline support
|
|
|
9 3. **pwa-register.js** - Service worker registration
|
|
|
10 4. **offline.html** - Offline fallback page
|
|
|
11 5. **Updated base_head.html** - Links to manifest and PWA script
|
|
|
12
|
|
|
13 ## Missing: App Icons
|
|
|
14
|
|
|
15 You need to create PNG icons from your SVG. Run these commands:
|
|
|
16
|
|
|
17 ### Using ImageMagick (recommended):
|
|
|
18
|
|
|
19 ```bash
|
|
|
20 cd src/public
|
|
|
21
|
|
|
22 # 192x192 icon
|
|
|
23 convert epi_all_colors.svg -resize 192x192 -background none icon-192.png
|
|
|
24
|
|
|
25 # 512x512 icon
|
|
|
26 convert epi_all_colors.svg -resize 512x512 -background none icon-512.png
|
|
|
27
|
|
|
28 # Maskable icon (512x512 with safe zone)
|
|
|
29 convert epi_all_colors.svg -resize 409x409 -background none -gravity center -extent 512x512 icon-maskable-512.png
|
|
|
30 ```
|
|
|
31
|
|
|
32 ### Or using Inkscape:
|
|
|
33
|
|
|
34 ```bash
|
|
|
35 inkscape epi_all_colors.svg --export-type=png --export-filename=icon-192.png -w 192 -h 192
|
|
|
36 inkscape epi_all_colors.svg --export-type=png --export-filename=icon-512.png -w 512 -h 512
|
|
|
37 inkscape epi_all_colors.svg --export-type=png --export-filename=icon-maskable-512.png -w 512 -h 512
|
|
|
38 ```
|
|
|
39
|
|
|
40 ### Or use an online tool:
|
|
|
41 - https://realfavicongenerator.net/
|
|
|
42 - https://www.pwabuilder.com/
|
|
|
43
|
|
|
44 ## Optional: Screenshots (for better app install experience)
|
|
|
45
|
|
|
46 Create screenshots of your site:
|
|
|
47
|
|
|
48 ```bash
|
|
|
49 # Mobile screenshot (540x720)
|
|
|
50 screenshot-mobile.png
|
|
|
51
|
|
|
52 # Desktop screenshot (1280x720)
|
|
|
53 screenshot-desktop.png
|
|
|
54 ```
|
|
|
55
|
|
|
56 You can use browser DevTools to capture these, or remove the `screenshots` section from manifest.json if you don't want them.
|
|
|
57
|
|
|
58 ## Testing Your PWA
|
|
|
59
|
|
|
60 1. **Serve over HTTPS** - PWAs require HTTPS (localhost works for testing)
|
|
|
61 2. **Open Chrome DevTools** → Application tab → Manifest
|
|
|
62 3. **Check Service Worker** → Application tab → Service Workers
|
|
|
63 4. **Lighthouse Audit** → Run PWA audit to see score
|
|
|
64
|
|
|
65 ## Install Prompt
|
|
|
66
|
|
|
67 When users visit your site, they'll see an "Install App" button in the bottom-right corner for 10 seconds. They can:
|
|
|
68 - Click it to install immediately
|
|
|
69 - Use browser menu: "Install MrJuneJune" or "Add to Home Screen"
|
|
|
70
|
|
|
71 ## Features
|
|
|
72
|
|
|
73 ✅ **Offline Support** - Caches pages, CSS, JS, fonts, images
|
|
|
74 ✅ **App Shortcuts** - Quick access to Blog and Notes
|
|
|
75 ✅ **Install Prompt** - Automatic install button
|
|
|
76 ✅ **Auto-updates** - Service worker updates on reload
|
|
|
77 ✅ **Fast Loading** - Cached resources load instantly
|
|
|
78
|
|
|
79 ## Customization
|
|
|
80
|
|
|
81 Edit `manifest.json` to change:
|
|
|
82 - `theme_color` - App theme color
|
|
|
83 - `background_color` - Splash screen color
|
|
|
84 - `display` - `standalone`, `fullscreen`, `minimal-ui`, or `browser`
|
|
|
85 - `shortcuts` - App shortcut menu items
|
|
|
86
|
|
|
87 Edit `sw.js` to change:
|
|
|
88 - `CACHE_VERSION` - Increment to force cache refresh
|
|
|
89 - `STATIC_CACHE` - Files to cache immediately
|
|
|
90 - Caching strategy (currently: cache-first with network fallback)
|
|
|
91
|
|
|
92 ## Testing on Mobile
|
|
|
93
|
|
|
94 ### Android:
|
|
|
95 1. Open Chrome
|
|
|
96 2. Visit your site
|
|
|
97 3. Tap menu → "Install app" or "Add to Home Screen"
|
|
|
98
|
|
|
99 ### iOS (Safari):
|
|
|
100 1. Open Safari
|
|
|
101 2. Tap Share button
|
|
|
102 3. Tap "Add to Home Screen"
|
|
|
103
|
|
|
104 Note: iOS has limited PWA support (no install prompt, limited background features)
|
|
|
105
|
|
|
106 ## Debugging
|
|
|
107
|
|
|
108 Check console for:
|
|
|
109 - `[PWA]` - Registration events
|
|
|
110 - `[SW]` - Service worker caching events
|
|
|
111
|
|
|
112 Clear cache:
|
|
|
113 ```js
|
|
|
114 navigator.serviceWorker.controller.postMessage({ type: 'CLEAR_CACHE' });
|
|
|
115 ```
|
|
|
116
|
|
|
117 ## Next Steps
|
|
|
118
|
|
|
119 1. Generate the PNG icons (see commands above)
|
|
|
120 2. Test on HTTPS
|
|
|
121 3. Run Lighthouse audit
|
|
|
122 4. Deploy and test on mobile device
|
|
|
123 5. Consider adding:
|
|
|
124 - Push notifications
|
|
|
125 - Background sync
|
|
|
126 - Share target API
|
