PWA and the Dev Loop
Installable and Offline (PWA)
Wisp serves src/manifest.json at /manifest.webmanifest and every page links it. Without the file, nothing is emitted.
{ "name": "Notes", "theme_color": "#7c3aed", "offline": true }
- Defaults:
short_name/name,start_url/,displaystandalone, andiconsfromstatic/icon*.pngandstatic/icon*.svg(maskablein the name sets"purpose": "maskable"). A manifest that listsiconskeeps its own. - One
static/icon.png(512 px or more) is enough;wisp buildalso writes 192 and 512 px WebP into/_app/img/with cwebp. - To set it at startup instead, call
wisp::app_manifest(r#"{"name": "Notes"}"#)?;ininit."offline"still goes insrc/manifest.json:app_manifestfails with a 500 when it holds"offline".
"offline": true adds Wisp's service worker. At install it keeps / (fetched without cookies, and only when it is not sent private or no-store), the browser files and static/; pages come from the network and are kept, except with a query string or Cache-Control: private/no-store. Offline, it serves the kept page or a 503.
The whole site, ahead: "offline": "all"
{ "name": "Notes", "offline": "all" } also fetches ahead every page that is the same for everyone, so a link works offline even if never visited.
- Which: a baked page, each path
wisp buildprerendered, and aCACHE_PUBLICpage with no parameter. Never a page with a form action, under(private), noindex, guarded (SIGNED_IN,MIDDLEWARE), reading the request, or sentprivateorno-store.const PRECACHE: bool = false;in a page or+layoutleaves pages out. - When: browser idle, not with data saver or on 2G; 5 MB at most, pages already kept included.
- Address: a route with
TRAILING_SLASH = Always(orwisp::trailing_slash(Always)) is fetched ahead under its address with the slash, as the server answers that address with 200. - Base path: the cache names include the
WISP_BASE, so two apps on one origin keep their own caches. The worker deletes its caches itself only when/service-worker.jsanswers 404, 410, or 200 with a reply that is not JavaScript. A redirect never deletes them. An app with a base path leaves the old cacheswisp-<version>andwisp-pagesin the browser. The worker never serves them. - Fresh: the worker fetches again, after a build, only pages whose content hash changed. It fetches a
CACHE_PUBLICpage again after each show. Withpublic_env = true, the worker fetches prerendered and baked pages again after each show, as the server changes their env tag at start. - To turn it off, remove
offline; the worker removes itself.
Your own src/service-worker.js (or .ts) replaces it. It is a classic script at /service-worker.js and imports only 'wisp/sw'.
wisp dev registers no worker. To try offline, use wisp build and the built binary.
import { build, files, version } from 'wisp/sw' // browser files, static/ files, hash of both and of the worker code (empty in dev)
self.addEventListener('install', (e) => {
e.waitUntil(caches.open(`app-${version}`).then((c) => c.addAll([...build, ...files])))
})
Dev: Hot Reload
wisp dev applies a .wisp save with no compile when only browser code or static text changed:
- A script or
{:…}change swaps the file's module (instances rerun it and keep$state, focus and field values). - Text alone morphs that file's part;
<style>swaps the stylesheet; otherwise it compiles and morphs.
Instances restart (one console line says why) when the --- block or {@props} changed, when the script has a top-level statement other than declarations, logging, writes to its own names and instance-ending helpers ($effect, onMount, setInterval…). When the swap throws, the page loads again.
Build errors show in a dialog whose src/…:line lines open in the editor, as does an error no {:#try} catches. Release builds have none of this.
Devtools
Alt+Shift+W opens dev-only devtools:
- Component tree with live props and state (editable), stores.
- A graph per component: what reads each signal.
- The route (params, server values, the page's forms), a table of all the app's routes.
- Timings: the browser timings of the last page load or navigation (server wait, download, draw).
- The
Server-Timingheader is a separate fact:WISP_SERVER_TIMINGadds it, on in dev. Only an answer that a route handler or its error page made has the header. An early upload refusal (a 429 or the sign-in answer) has none. - A server panic or other 5xx opens the same error dialog with its message and
file:line. "Open" uses$WISP_EDITORor$EDITOR, elsecode -g.
Is This Page Useful?