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

Wisp

Islands and Loading

Islands

A page ships JS only for files with client code. A component can wait:

<Chart client:visible />                        <!-- near the viewport (200px) -->
<Comments client:idle />                        <!-- browser idle -->
<Filters client:media="(min-width: 800px)" />   <!-- query matches -->
<Menu client:interaction />                     <!-- first pointer, focus or key -->
<Badge client:none />                           <!-- never: no module, no values -->
<section client:visible>{:#each rows as row}…{:/each}</section>   <!-- an element with browser code -->
  • client:load (default) starts with the page.
  • The server paints every island, so it works as HTML until it wakes.
  • client:* on a component needs it to have browser code. A component without any is a server component (no JS), and they nest with islands in any order.

React, Vue, Svelte, Preact

wisp npm add react react-dom react-switch (framework first), then:

<Island
  of="react:react-switch"
  client:visible
  props={:{ checked: on, onChange: (v) => (on = v) }} />
<p>{:on ? 'On' : 'Off'}</p>
<script lang="ts">
  let on = false
</script>
  • of="framework:module" (react preact vue svelte). #Name picks a named export (react:recharts#LineChart); $lib works.
  • props={:…} is browser (state, callbacks, redraws on change). props=${rows} is Rust, sent once as JSON.
  • Children show until it starts. An <Island> inside another's children is a build error, so put islands side by side. Other attributes (class, id) go on its <div>.
  • The framework must be in package.json. A Svelte package must ship compiled JS.

Web Components

Import the module, write the tag (Shoelace, Web Awesome wa-, Lit). on: takes their events (dashes too). bind:value listens for input.

<sl-input label="Name" bind:value="name"></sl-input>
<sl-switch on:sl-change="on = event.target.checked">Power</sl-switch>
<script lang="ts">
  import '@shoelace-style/shoelace/dist/components/input/input.js'
  import '@shoelace-style/shoelace/dist/components/switch/switch.js'
  let on = false
</script>
  • Run wisp npm add @shoelace-style/shoelace and import each component's own module.
  • Theme CSS: copy it into static/ and <link> it in src/app.html, or @import a CDN after wisp::csp("style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net") in init.
  • For your own element, wisp npm add lit and call customElements.define(...) in a src/lib module a script imports.

Your Own Bundle

For a widget wisp npm add cannot serve, bundle it into static/ with your own tool (esbuild, vite) and mount it from a use: action. data-wisp-keep stops a morph from touching what the widget draws.

<div data-wisp-keep use:widget="{ label }"></div>
<script lang="ts">
  function widget(el, props) {            // mount(el, props), update(props), destroy()
    let w
    import('/widget.js').then((m) => (w = m.mount(el, props)))
    return { update: (p) => w?.update(p), destroy: () => w?.destroy() }
  }
</script>

destroy runs when the element leaves the page.

Third-Party Scripts

Pick when one loads. In the head:

TagLoads
<script src>before interactive
<script defer src>after interactive
<script src="https://t.example/a.js" type="wisp/idle">when the browser is idle
type="wisp/interaction"at the first pointer, key or scroll
<script src="…" type="wisp/idle" on:load="ready = true">runs on:load once the script has loaded (put it in the page body; hydration runs first). async, defer and type="module" pass through as written

Other attributes (async, data-*) are copied.

Loading Views

src/routes/blog/+loading.wisp is static HTML (no --- block, holes or components). A client navigation to /blog or any page below it shows the view in <main> if the page has not arrived within 100 ms, with aria-busy set. A faster page just morphs in.

  • The deepest folder that fits wins. routes/+loading.wisp is for every page. A +loading.wisp in a (group) folder is for the pages below that folder only.
  • A view in a @slot folder (dash/@feed/[id]/+loading.wisp) shows in that slot's <wisp-slot> (Slots).

Web Vitals

<meta name="wisp-vitals" content="/vitals"> (in src/app.html) is opt-in. When the page is hidden, wisp.js sends that path one beacon (sendBeacon, a POST) of JSON: {"path":"/x","ttfb":12,"lcp":480.5,"cls":0.02,"inp":64}. Client navigations do not count. Receive it with vitals/+server.rs: fn post(cx: &mut Cx) -> Result<()> reading cx.body().

Browser Errors

<meta name="wisp-errors" content="/errors"> (in the head of src/app.html) is opt-in, as the client handleError hook of SvelteKit. The build sees it, and each page loads /_app/c/errors.js. An uncaught error or an unhandled promise rejection sends that path one beacon (sendBeacon, a POST of JSON text with content-type: text/plain): {"kind":"error","message":"boom","source":"https://x/_app/c/a.js","line":3,"col":9,"stack":"…","path":"/x"}. kind is error or rejection.

  • A page load sends at most 5 reports, and one report for each message and place (source, line, col). A new page load starts the count again.
  • message, source and path hold at most 500 characters, stack at most 2000.
  • URLs in message, source and stack lose their query and hash. The report has no cookies and no form values.
  • message is the app's own error text, and it can hold personal data. path can hold a token or an e-mail address (/reset/<token>). The route must treat both as personal data.
  • errors.js is a module, so it runs after the page is parsed. It does not see an error before that (an inline script in the head) or a failure to load errors.js.
  • The build looks for the meta only in the head of src/app.html. It also finds a meta in an HTML comment there. A meta in a template does not count.
  • The reporter catches its own failures. It does not send them.
  • An app without the meta loads no file and adds no listener.

Receive it with errors/+server.rs: fn post(cx: &mut Cx) -> Response reading cx.body(), which returns Response::empty(204). The route is open to all clients, so treat the body as untrusted text. Limit it with const BODY_LIMIT: usize = 24 * wisp::KB; and const RATE_LIMIT: u32 = 30;, and log it escaped ({:?}).

Loading Code on Demand

import() loads code when the page reaches it:

<button on:click="import('$lib/chart.js').then((m) => m.draw(el))">Chart</button>
  • It resolves like a static import: $lib/x.js (or $lib/x), a relative path into src/lib, or an NPM package. A missing path, or one outside src/lib, is a build error.
  • There is no bundle: each lib file, component and package is one immutable hashed URL.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.