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:

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:

  1. 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.)
  2. Start your app as usual on port 8000.
  3. 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:

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

This Week's Exercise

  1. Read T17, then open static/manifest.webmanifest and static/sw.js and explain each line in plain words.
  2. Share your app with tailscale serve 8000 and open it on your phone.
  3. Add it to the home screen. Open it in airplane mode and note what works and what does not.
  4. 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