Wisp is in pre-release, self-hosted since GitHub suspended us. Install it, or see the changelog.

Wisp

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 /, display standalone, and icons from static/icon*.png and static/icon*.svg (maskable in the name sets "purpose": "maskable"). A manifest that lists icons keeps its own.
  • One static/icon.png (512 px or more) is enough; wisp build also writes 192 and 512 px WebP into /_app/img/ with cwebp.
  • To set it at startup instead, call wisp::app_manifest(r#"{"name": "Notes"}"#)?; in init. "offline" still goes in src/manifest.json: app_manifest fails 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 build prerendered, and a CACHE_PUBLIC page with no parameter. Never a page with a form action, under (private), noindex, guarded (SIGNED_IN, MIDDLEWARE), reading the request, or sent private or no-store. const PRECACHE: bool = false; in a page or +layout leaves 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 (or wisp::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.js answers 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 caches wisp-<version> and wisp-pages in 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_PUBLIC page again after each show. With public_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-Timing header is a separate fact: WISP_SERVER_TIMING adds 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_EDITOR or $EDITOR, else code -g.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.