Mercurial
annotate mrjunejune/PWA_SETUP.md @ 251:117c4d53c9a4
[ui] Add HTML-first Web Component system
Co-authored-by: Copilot <[email protected]>
| author | MrJuneJune <me@mrjunejune.com> |
|---|---|
| date | Tue, 04 Aug 2026 09:14:57 -0700 |
| parents | 9c2eec61a152 |
| children | e02e2036ef84 |
| rev | line source |
|---|---|
| 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 | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
13 ## App Icons and WebP Assets |
| 209 | 14 |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
15 All shipped raster images are generated as WebP by Bazel. Source PNGs live |
|
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
16 under `mrjunejune/assets/png/` and are never copied into the release bundle. |
| 209 | 17 |
| 18 ```bash | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
19 bazel build //mrjunejune:generated_webp_assets |
| 209 | 20 ``` |
| 21 | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
22 The complete site bundle also runs the conversion pipeline: |
| 209 | 23 |
| 24 ```bash | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
25 bazel build //mrjunejune:mrjunejune_server_bundle |
| 209 | 26 ``` |
| 27 | |
| 28 ## Optional: Screenshots (for better app install experience) | |
| 29 | |
| 30 Create screenshots of your site: | |
| 31 | |
| 32 ```bash | |
| 33 # Mobile screenshot (540x720) | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
34 screenshot-mobile.webp |
| 209 | 35 |
| 36 # Desktop screenshot (1280x720) | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
37 screenshot-desktop.webp |
| 209 | 38 ``` |
| 39 | |
|
241
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
40 You can use browser DevTools to capture these. Add their PNG sources to the |
|
9c2eec61a152
[assets] Generate site images as WebP with Bazel
MrJuneJune <me@mrjunejune.com>
parents:
209
diff
changeset
|
41 WebP asset list before referencing the generated `.webp` files in the manifest. |
| 209 | 42 |
| 43 ## Testing Your PWA | |
| 44 | |
| 45 1. **Serve over HTTPS** - PWAs require HTTPS (localhost works for testing) | |
| 46 2. **Open Chrome DevTools** → Application tab → Manifest | |
| 47 3. **Check Service Worker** → Application tab → Service Workers | |
| 48 4. **Lighthouse Audit** → Run PWA audit to see score | |
| 49 | |
| 50 ## Install Prompt | |
| 51 | |
| 52 When users visit your site, they'll see an "Install App" button in the bottom-right corner for 10 seconds. They can: | |
| 53 - Click it to install immediately | |
| 54 - Use browser menu: "Install MrJuneJune" or "Add to Home Screen" | |
| 55 | |
| 56 ## Features | |
| 57 | |
| 58 ✅ **Offline Support** - Caches pages, CSS, JS, fonts, images | |
| 59 ✅ **App Shortcuts** - Quick access to Blog and Notes | |
| 60 ✅ **Install Prompt** - Automatic install button | |
| 61 ✅ **Auto-updates** - Service worker updates on reload | |
| 62 ✅ **Fast Loading** - Cached resources load instantly | |
| 63 | |
| 64 ## Customization | |
| 65 | |
| 66 Edit `manifest.json` to change: | |
| 67 - `theme_color` - App theme color | |
| 68 - `background_color` - Splash screen color | |
| 69 - `display` - `standalone`, `fullscreen`, `minimal-ui`, or `browser` | |
| 70 - `shortcuts` - App shortcut menu items | |
| 71 | |
| 72 Edit `sw.js` to change: | |
| 73 - `CACHE_VERSION` - Increment to force cache refresh | |
| 74 - `STATIC_CACHE` - Files to cache immediately | |
| 75 - Caching strategy (currently: cache-first with network fallback) | |
| 76 | |
| 77 ## Testing on Mobile | |
| 78 | |
| 79 ### Android: | |
| 80 1. Open Chrome | |
| 81 2. Visit your site | |
| 82 3. Tap menu → "Install app" or "Add to Home Screen" | |
| 83 | |
| 84 ### iOS (Safari): | |
| 85 1. Open Safari | |
| 86 2. Tap Share button | |
| 87 3. Tap "Add to Home Screen" | |
| 88 | |
| 89 Note: iOS has limited PWA support (no install prompt, limited background features) | |
| 90 | |
| 91 ## Debugging | |
| 92 | |
| 93 Check console for: | |
| 94 - `[PWA]` - Registration events | |
| 95 - `[SW]` - Service worker caching events | |
| 96 | |
| 97 Clear cache: | |
| 98 ```js | |
| 99 navigator.serviceWorker.controller.postMessage({ type: 'CLEAR_CACHE' }); | |
| 100 ``` | |
| 101 | |
| 102 ## Next Steps | |
| 103 | |
| 104 1. Generate the PNG icons (see commands above) | |
| 105 2. Test on HTTPS | |
| 106 3. Run Lighthouse audit | |
| 107 4. Deploy and test on mobile device | |
| 108 5. Consider adding: | |
| 109 - Push notifications | |
| 110 - Background sync | |
| 111 - Share target API |