Mercurial
annotate mrjunejune/PWA_SETUP.md @ 273:e02e2036ef84 default tip
add Layer 2 JRPG component system
Add reusable content and window modals, an isolated component sandbox, shared cyberpunk scroll areas, production-safe cache freshness, and server-rendered JRPG panel state.
Co-authored-by: Copilot <[email protected]>
| author | MrJuneJune <me@mrjunejune.com> |
|---|---|
| date | Sat, 08 Aug 2026 02:08:08 -0700 |
| parents | 9c2eec61a152 |
| children |
| 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 | |
|
273
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
61 ✅ **Auto-updates** - New service workers activate and reload clients automatically |
| 209 | 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 | |
|
273
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
75 - Caching strategy: |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
76 - HTML, CSS, JS, JSON, and WASM are network-first with offline cache fallback. |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
77 - Fonts and images are stale-while-revalidate. |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
78 - Component sandbox assets always bypass service-worker caching. |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
79 |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
80 Unversioned application code must not use cache-first. That can preserve stale |
|
e02e2036ef84
add Layer 2 JRPG component system
MrJuneJune <me@mrjunejune.com>
parents:
241
diff
changeset
|
81 production CSS or JavaScript indefinitely when a deployment reuses the same URL. |
| 209 | 82 |
| 83 ## Testing on Mobile | |
| 84 | |
| 85 ### Android: | |
| 86 1. Open Chrome | |
| 87 2. Visit your site | |
| 88 3. Tap menu → "Install app" or "Add to Home Screen" | |
| 89 | |
| 90 ### iOS (Safari): | |
| 91 1. Open Safari | |
| 92 2. Tap Share button | |
| 93 3. Tap "Add to Home Screen" | |
| 94 | |
| 95 Note: iOS has limited PWA support (no install prompt, limited background features) | |
| 96 | |
| 97 ## Debugging | |
| 98 | |
| 99 Check console for: | |
| 100 - `[PWA]` - Registration events | |
| 101 - `[SW]` - Service worker caching events | |
| 102 | |
| 103 Clear cache: | |
| 104 ```js | |
| 105 navigator.serviceWorker.controller.postMessage({ type: 'CLEAR_CACHE' }); | |
| 106 ``` | |
| 107 | |
| 108 ## Next Steps | |
| 109 | |
| 110 1. Generate the PNG icons (see commands above) | |
| 111 2. Test on HTTPS | |
| 112 3. Run Lighthouse audit | |
| 113 4. Deploy and test on mobile device | |
| 114 5. Consider adding: | |
| 115 - Push notifications | |
| 116 - Background sync | |
| 117 - Share target API |