Expand description
Browser-side runtime for Krab’s island architecture.
Krab renders a page on the server and ships it as HTML. Only the
interactive parts — islands — are then brought to life in the browser by
this crate. It is the WASM half of the framework: it adopts the
server-rendered DOM instead of rebuilding it, wires event listeners onto the
nodes that are already there, and keeps Node::Dynamic regions in sync
with the reactive graph re-exported from krab_core.
§The web feature
Everything that touches the DOM is behind the web feature. Without it the
crate still compiles — so a workspace-wide cargo check on the host target
succeeds — but hydrate does nothing and the DOM entry points below are
not compiled at all. Anything built for the browser must enable web.
The optional debug feature adds informational console.log tracing of the
hydration pass. Warnings and errors are always reported; debug only
controls the chatter, so production bundles stay quiet.
§The hydration model
The server emits each island as an element carrying data-island (the
registered component name), data-props (its JSON props), and a
data-krab-boundary-id. hydrate finds those elements, rebuilds each
island’s virtual tree by calling the factory registered for its name, and
walks that tree against the live DOM:
- a matching element is reused, and its listeners are attached to it;
- a text node whose content differs is patched in place, which is what lets a selection or an IME composition survive hydration;
- only a genuine shape mismatch causes a node to be replaced.
Every boundary is stamped with the outcome — data-krab-boundary-state
(ok, patched, error, missing-definition, …) and
data-krab-boundary-mismatches — so monitoring can see a drifting boundary
without reading the console.
That stamp is also what makes hydration idempotent. The server ships
data-krab-boundary-state="ssr"; a boundary whose state has moved off ssr
is skipped, so a second pass cannot bind a second copy of every handler.
unmount reverses a pass — releasing event closures and dynamic-region
effects, and clearing the stamp — so unmount followed by
hydrate_within is a supported re-hydration cycle.
§Usage
Islands register themselves; the application only has to call hydrate
once the WASM module is loaded.
use krab_client::{create_signal, hydrate};
use krab_macros::{island, view};
#[island]
fn Counter(start: i32) -> Node {
let (count, set_count) = create_signal(start);
view! {
<button on:click={move |_| set_count.set(count.get() + 1)}>
{move || count.get().to_string()}
</button>
}
}
// Exported entry point, called by the page's module script once the WASM
// module is instantiated. NOT `#[wasm_bindgen(start)]`: `krab_client`
// already owns the bundle's single start function, and a second one is a
// wasm-bindgen error.
#[wasm_bindgen]
pub fn krab_boot() {
hydrate();
}The page loads it from a same-origin module file (an inline script is
blocked by Krab’s CSP, script-src 'self' 'wasm-unsafe-eval'):
import init, { krab_boot } from '/pkg/my_app.js';
init().then(() => krab_boot());examples/reference_apps/islands_rpc does exactly this, and also starts the
client router after hydrating.
To bring up a fragment that arrived after the initial load — a modal, a client-routed view — hydrate just that subtree, and release it when it goes away:
krab_client::hydrate_within(&panel);
// …later…
krab_client::unmount(&panel);
panel.remove();Modules§
- router
- Client-side routing: same-origin navigation without a full page load.
Structs§
- Action
- An async operation with
pending,value, anderrorexposed as signals. - Effect
Handle - A handle to an effect created with
create_effect_scoped. - Island
Definition - Memo
- A cached derived value that recomputes only when a dependency changed.
- Owner
- A context scope: the unit
provide_contextwrites to anduse_contextsearches from. - Read
Signal - The read half of a signal, from
create_signal. Reading it inside an effect or memo subscribes that effect or memo to later writes. - Resource
- An async read with
stateandvalueexposed as signals. - Write
Signal - The write half of a signal, from
create_signal.
Enums§
- Resource
State - Where a
Resourceis in its load cycle.
Functions§
- batch
- Group writes so dependent effects run once, after the last one.
- create_
action - Wrap an async operation as an
Action. - create_
effect - Run
fnow, and again whenever a signal it read changes. - create_
effect_ scoped - Like
create_effect, but returns anEffectHandlethat can tear the effect down. - create_
memo - Create a cached derived value.
- create_
resource - Create a
Resourcethat fetches on creation and refetches whensourcechanges. - create_
resource_ with_ initial - Create a
Resourcethat startsReadywith a server-provided value and does not fetch on creation. - create_
signal - Creates a signal holding
value, returning its read and write halves. - hydrate
- Hydrate every island in the document.
- hydrate_
island - Hydrate one island element, and nothing else.
- hydrate_
within - Hydrate only the islands inside
root. Skips boundaries already hydrated. - hydrate_
within_ selector - Hydrate every element in the document matching
selector— each one itself if it is an island, and every island inside it. - log_
hydration_ diagnostic - on_
cleanup - Register a callback to run when the current effect is disposed or re-runs.
- provide_
context - Make
valueavailable touse_context::<T>()in the current scope and every scope created inside it. - start
- unmount
- Release every runtime resource held by
root’s subtree: event closures, dynamic-region registrations, and region effects. Does not removeroot. - untrack
- Read signals without subscribing to them.
- use_
context - The nearest value of type
Tprovided in the current scope or any scope enclosing it, orNoneif there is none. - with_
owner - Run
fin a new context scope, parented to the current one.