Full Stack Web

Leptos is a full stack web framework. The first recipe renders HTML on the server only. The second adds hydration so the client can re-run the same components as WebAssembly for interactivity.

Return filtered results as HTML

[![leptos-badge]][leptos] [![leptos-router-badge]][leptos-router] [![leptos-axum-badge]][leptos-axum] [![axum-badge]][axum] [![tokio-badge]][tokio] [![cat-net-badge]][cat-net]

The crate uses [leptos][leptos] with the ssr feature, plus [leptos_router][leptos-router], [leptos_axum][leptos-axum], [axum][axum], and [tokio][tokio]. It lives outside the main workspace because leptos needs resolver = "3".

Define the router

Router is responsible for what page is shown when the browser hits the app. The path! macro is used to define what URL matches. The :query is a template — it matches anything and stores the value as query for the component to read later.

{{#include ../../crates/web_leptos/src/main.rs:10:23}}

<A> anchors links while <Routes fallback=...> is used to provide a default.

More in the Leptos book: Defining <Routes/> and Nested Routing.

Read the parameter and fetch on the server

use_params holds the values from the Router. Resource::new uses a closure to fetch async. The closure runs on the server and <Suspense> lets the user know the server is processing.

{{#include ../../crates/web_leptos/src/main.rs:33:61}}

filter_crates is a plain async fn that runs on the server. It resolves the data file via env!("CARGO_MANIFEST_DIR") so the path works regardless of where the binary runs from.

{{#include ../../crates/web_leptos/src/main.rs:73:84}}

More in the Leptos book: Params and Queries, Loading Data with Resources, and Suspense.

Write a reusable component

Components are functions annotated with #[component]. Props are ordinary function arguments.

{{#include ../../crates/web_leptos/src/main.rs:63:71}}

More in the Leptos book: Components and Props and Passing Children to Components.

Wire up Axum

generate_route_list(App) walks the Routes tree to enumerate every path the router knows about. leptos_routes registers those paths as Axum GET handlers that render the shell on each request.

{{#include ../../crates/web_leptos/src/main.rs:86:120}}

More in the Leptos book: The Life of a Page Load and cargo-leptos (the tool most real apps graduate to).

Run it:

cargo run --manifest-path crates/web_leptos/Cargo.toml
# http://127.0.0.1:3000/
# http://127.0.0.1:3000/filter/serde
# http://127.0.0.1:3000/filter/tokio

Synchronize component state with the server

[![leptos-badge]][leptos] [![leptos-axum-badge]][leptos-axum] [![axum-badge]][axum] [![tokio-badge]][tokio] [![wasm-bindgen-badge]][wasm-bindgen] [![cat-net-badge]][cat-net]

Same data/crates.txt as the first recipe, but the user types in a text box and results update as they type — no page reload. The file stays on the server; the query round-trips through a server function.

The recipe uses cargo-leptos as the build tool and a wasm32-unknown-unknown target:

cargo install cargo-leptos
rustup target add wasm32-unknown-unknown

Split ssr and hydrate with feature flags

One crate, two builds. ssr pulls in the server deps and hydrate turns on the WASM client. cargo-leptos drives both from [package.metadata.leptos].

{{#include ../../crates/web_leptos_hydrate/Cargo.toml:10:41}}

Put the filter behind a server function

#[server] makes filter_crates a function the client can call. The body only compiles into the ssr build and on hydrate the macro leaves a stub that POSTs to the server. tokio::fs reads the file on the server as before.

{{#include ../../crates/web_leptos_hydrate/src/lib.rs:10:20}}

Bind an input to a resource

The App component is plain reactive Leptos — not behind ssr nor hydrate. signal holds the query, event_target_value pulls the string out of each keystroke, and Resource::new reruns filter_crates whenever the query changes. <Suspense> paints results or the "Searching..." fallback.

{{#include ../../crates/web_leptos_hydrate/src/lib.rs:22:50}}

Server side: render the shell with HydrationScripts

<HydrationScripts> emits the <script> tag that loads the WASM bundle. <AutoReload> ships a reload script when cargo leptos watch is running.

{{#include ../../crates/web_leptos_hydrate/src/lib.rs:52:67}}

Client side: hydrate the body

hydrate_body runs the same App function in the browser and attaches it to the server-rendered DOM. #[wasm_bindgen] marks it as the entry point the generated JS will call.

{{#include ../../crates/web_leptos_hydrate/src/lib.rs:69:74}}

Wire up Axum behind the ssr feature

get_configuration reads the [package.metadata.leptos] section. leptos_routes also registers the server function endpoint automatically.

{{#include ../../crates/web_leptos_hydrate/src/main.rs}}

Run it:

cd crates/web_leptos_hydrate
cargo leptos watch
# http://127.0.0.1:3000/

More in the Leptos book: Server Functions and cargo-leptos.

{{#include ../links.md}}