Skip to main content

Crate krab_client

Crate krab_client 

Source
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, and error exposed as signals.
EffectHandle
A handle to an effect created with create_effect_scoped.
IslandDefinition
Memo
A cached derived value that recomputes only when a dependency changed.
Owner
A context scope: the unit provide_context writes to and use_context searches from.
ReadSignal
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 state and value exposed as signals.
WriteSignal
The write half of a signal, from create_signal.

Enums§

ResourceState
Where a Resource is 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 f now, and again whenever a signal it read changes.
create_effect_scoped
Like create_effect, but returns an EffectHandle that can tear the effect down.
create_memo
Create a cached derived value.
create_resource
Create a Resource that fetches on creation and refetches when source changes.
create_resource_with_initial
Create a Resource that starts Ready with 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 value available to use_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 remove root.
untrack
Read signals without subscribing to them.
use_context
The nearest value of type T provided in the current scope or any scope enclosing it, or None if there is none.
with_owner
Run f in a new context scope, parented to the current one.

Type Aliases§

ComponentFactory