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).#Namepicks a named export (react:recharts#LineChart);$libworks.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/shoelaceand import each component's own module. - Theme CSS: copy it into
static/and<link>it insrc/app.html, or@importa CDN afterwisp::csp("style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net")ininit. - For your own element,
wisp npm add litand callcustomElements.define(...)in asrc/libmodule 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:
| Tag | Loads |
|---|---|
<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.wispis for every page. A+loading.wispin a(group)folder is for the pages below that folder only. - A view in a
@slotfolder (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,sourceandpathhold at most 500 characters,stackat most 2000.- URLs in
message,sourceandstacklose their query and hash. The report has no cookies and no form values. messageis the app's own error text, and it can hold personal data.pathcan 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 intosrc/lib, or an NPM package. A missing path, or one outsidesrc/lib, is a build error. - There is no bundle: each lib file, component and package is one immutable hashed URL.
Is This Page Useful?