W13: On the Phone: an Installable App (PWA)
A food truck and a restaurant can serve the same dishes. The truck just parks closer to you. A PWA (progressive web app) is your same web app, parked on the phone's home screen: an icon, opening full screen with no browser bar, and still showing something when the signal drops. No app store, no second codebase, no new language. The starter is already a PWA. This lesson gets it onto your phone.
Why a PWA First
The stack has one way for phones, and it starts here. A PWA:
- Is the same code as your web app: every change reaches the phone too.
- Works on iPhone and Android, with no store, no review, no fee.
A native app (W15) is the second step, only when an app needs something a PWA cannot do.
The Three Pieces
T17: Dynamic Site: Offline explains how PWAs work, and A18's "Make it installable" builds one for a game. The starter already has all three pieces:
1. A manifest, static/manifest.webmanifest, describing the app to the phone:
{
"name": "Notes",
"short_name": "Notes",
"start_url": "/",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#000000",
"icons": [{"src": "/static/icon.svg", "sizes": "any", "type": "image/svg+xml"}]
}
"display": "standalone" is the line that removes the browser bar. base.html links it with <link rel="manifest" href="/manifest.webmanifest">.
2. A service worker, static/sw.js: a small script the browser keeps beside your app. It sees every request first. The starter's worker saves the app's shell (the home page, the CSS, htmx, Basecoat's script, the icon) when it installs, then always tries the network first and falls back to the saved copy when there is no connection.
3. The registration, one line in base.html:
<script>if ("serviceWorker" in navigator) navigator.serviceWorker.register("/sw.js");</script>
app/main.py serves sw.js from the top of the site (/sw.js), so it can look after the whole app.
Getting It onto Your Phone
Here is the catch. Your app runs at http://127.0.0.1:8000, which means "this computer only". Your phone cannot open it. And service workers only work over HTTPS (except on the computer itself). So the phone needs an HTTPS address for your app.
The workbench already solves this for itself with Tailscale, a private network between your own devices. The same works for your app:
- Install Tailscale on your computer and your phone, and sign in to the same account on both. (If you set up phone access for the workbench, this is done.)
- Start your app as usual on port 8000.
- In another terminal, share it on your private network:
tailscale serve 8000
Tailscale prints an address like https://my-laptop.your-tailnet.ts.net. Only your own devices can open it; it is not public (W16 covers public). The first time, it may ask you to enable HTTPS for your network, with a link. It lasts while the command runs; Ctrl+C stops it.
If you turned on phone access for the workbench, the workbench already uses that main address. Give your app its own port instead, and open https://my-laptop.your-tailnet.ts.net:8443:
tailscale serve --https=8443 localhost:8000
Pi Workbench will do this step for you soon: the Preview will show your running app with a QR code to open it on the phone.
Install It
Open the address on the phone, then:
- iPhone (Safari): the Share button, then Add to Home Screen.
- Android (Chrome): the menu (⋮), then Install app or Add to Home screen.
Open it from the new icon. No browser bar: it looks like an app. Turn on airplane mode and open it again: the home page still appears from the saved copy. Adding a note needs the server, so that fails until you are back online. That is honest: your notes live in the SQLite file on your computer, not on the phone.
The Stale Copy Trap
A18 warns about this, and it applies here too. The saved copy has a name, shell-v1, in sw.js. When you change which files are saved, change the name too (shell-v2), so phones fetch the new set. If a phone keeps showing an old look after an update, this is the first suspect. Ask Pi:
"I changed the styles; make the service worker save a fresh copy, and delete the old one."
Make It Yours
- "Change the app's name and short name in the manifest to My Notes, and the theme colour to dark blue."
- "Replace the icon with a simple notebook drawing." (Some phones, iPhones especially, show a sharper icon from a PNG; ask Pi to add one if yours looks wrong.)
- "When the app is offline, show a small message 'Offline: showing your last copy' instead of failing silently."
This Week's Exercise
- Read T17, then open
static/manifest.webmanifestandstatic/sw.jsand explain each line in plain words. - Share your app with
tailscale serve 8000and open it on your phone. - Add it to the home screen. Open it in airplane mode and note what works and what does not.
- Ask Pi for the offline message, and test it the same way.
Key Takeaways
- A PWA is the same app, installed from the browser: no store, no second codebase, iPhone and Android
- The starter already has the three pieces: a manifest, a service worker at /sw.js, and its registration in base.html
- Phones need an HTTPS address: tailscale serve 8000 gives one, private to your own devices
- Install with Add to Home Screen (iPhone) or Install app (Android)
- Offline shows the saved copy; data still lives on the server. Rename the cache when the saved files change