Mercurial

comparison mrjunejune/PWA_SETUP.md @ 209:3b47e82ac57e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[MrJuneJune] PWA updates.
author MrJuneJune <me@mrjunejune.com>
date Sun, 15 Feb 2026 15:43:26 -0800
parents
children
comparison
equal deleted inserted replaced
208:5d3e116dd745 209:3b47e82ac57e
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